PHP Class Wire, ProcessWire

Inheritance: extends ElggObject
Mostrar archivo Open project: ryancramerdesign/ProcessWire Class Usage Examples

Public Properties

Property Type Description
$allLocalHooks Cache of all local hooks combined, for debugging purposes

Protected Properties

Property Type Description
$_notices ***************************************************************************************************** NOTICES AND LOGS
$defaultHookOptions - type: may be either 'method' or 'property'. If property, then it will respond to $obj->property rather than $obj->method(). - before: execute the hook before the method call? Not applicable if 'type' is 'property'. - after: execute the hook after the method call? (allows modification of return value). Not applicable if 'type' is 'property'. - priority: a number determining the priority of a hook, where lower numbers are executed before higher numbers. - allInstances: attach the hook to all instances of this object? (store in staticHooks rather than localHooks). Set automatically, but you may still use in some instances. - fromClass: the name of the class containing the hooked method, if not the object where addHook was executed. Set automatically, but you may still use in some instances. - argMatch: array of Selectors objects where the indexed argument (n) to the hooked method must match, order to execute hook. - objMatch: Selectors object that the current object must match in order to execute hook
$fuel Fuel | null Fuel holds references to other ProcessWire system objects. It is an instance of the Fuel class.
$hookMethodCache Hooked methods end with '()' while hooked properties don't. This does not distinguish which instance it was added to or whether it was removed. But will use keys in the form 'fromClass::method' (with value 'method') in cases where a fromClass was specified. This cache exists primarily to gain some speed in our __get and __call methods.
$localHooks Hooks that are local to this instance of the class only.
$staticHooks This array holds references to those static hooks, and is shared among all classes descending from Wire. It is for internal use only. See also self::$defaultHookOptions[allInstances].
$useFuel boolean Whether this class may use fuel variables in local scope, like $this->item

Public Methods

Method Description
_ ( string $text ) : string Translate the given text string into the current language if available.
___changed ( string $what, mixed $old = null, mixed $new = null ) Hookable method that is called whenever a property has changed while self::$trackChanges is true
___log ( string $str = '', array $options = [] ) : WireLog | null Log a message for this class
___trackException ( Exception $e, boolean | integer $severe = true, string | array | object | true $text = null ) Hookable method called when an Exception occurs
__call ( string $method, array $arguments ) : mixed Provides the gateway for calling hooks in ProcessWire
__construct ( )
__debugInfo ( ) : array debugInfo PHP 5.6+ magic method
__get ( string $name ) : mixed | null Get an object property by direct reference or NULL if it doesn't exist
__toString ( ) Unless overridden, classes descending from Wire return their class name when typecast as a string
_n ( string $textSingular, string $textPlural, integer $count ) : string Perform a language translation with singular and plural versions
_x ( string $text, string $context ) : string Perform a language translation in a specific context
addHook ( string $method, object | null | callable $toObject, string $toMethod = null, array $options = [] ) : string Hook a function/method to a hookable method call in this object
addHookAfter ( string $method, object | null | callable $toObject, string $toMethod = null, array $options = [] ) : string Shortcut to the addHook() method which adds a hook to be executed after the hooked method.
addHookBefore ( string $method, object | null | callable $toObject, string $toMethod = null, array $options = [] ) : string Shortcut to the addHook() method which adds a hook to be executed before the hooked method.
addHookProperty ( string $property, object | null | callable $toObject, string $toMethod = null, array $options = [] ) : string Shortcut to the addHook() method which adds a hook to be executed as an object property.
className ( array | null $options = null ) : string Return this object's class name
error ( string | array | Wire $text, integer | boolean $flags ) Record an non-fatal error message in the system-wide notices.
errors ( string | array $options = [] ) : Notices | string Return errors recorded by this object
fuel ( string $name ) : mixed | null Get the Fuel specified by $name or NULL if it doesn't exist
getAllFuel ( ) : Fuel Returns an iterable Fuel object of all Fuel currently loaded
getChanges ( boolean $getValues = false ) : array Return an array of properties that have changed while change tracking was on.
getFuel ( string $name = '' ) : mixed | null Get the Fuel specified by $name or NULL if it doesn't exist
getHooks ( string $method = '', integer $type ) : array Return all hooks associated with this class instance or method (if specified)
hasHook ( string $method ) : boolean Similar to isHooked(), returns true if the method or property hooked, false if it isn't.
isChanged ( string $what = '' ) : boolean Has the given property changed?
isHooked ( string $method, Wire $instance = null ) : boolean Returns true if the method/property hooked, false if it isn't.
message ( string | array | Wire $text, integer | boolean $flags ) Record an informational or 'success' message in the system-wide notices.
messages ( string | array $options = [] ) : Notices | string Return messages recorded by this object
removeHook ( string | null $hookId ) Given a Hook ID provided by addHook() this removes the hook
resetTrackChanges ( boolean $trackChanges = true ) Clears out any tracked changes and turns change tracking ON or OFF
runHooks ( string $method, array $arguments, string $type = 'method' ) : array Provides the implementation for calling hooks in ProcessWire
setFuel ( string $name, mixed $value, boolean $lock = false ) Add fuel to all classes descending from Wire
setTrackChanges ( boolean | integer $trackChanges = true ) Turn change tracking ON or OFF
trackChange ( string $what, mixed $old = null, mixed $new = null ) Track a change to a property in this object
trackChanges ( boolean $getMode = false ) : boolean | integer Returns true if change tracking is on, or false if it's not.
untrackChange ( string $what ) Untrack a change to a property in this object
useFuel ( boolean $useFuel = null ) : boolean Should fuel vars be scoped locally to this class instance?
warning ( string | array | Wire $text, integer | boolean $flags ) Record a warning error message in the system-wide notices.
warnings ( string | array $options = [] ) : Notices | string Return warnings recorded by this object
wire ( string | object $name = '', null | mixed $value = null, boolean $lock = false ) : ProcessWire | Wire | Session | Page | Pages | Modules | User | Users | Roles | Permissions | Templates | Fields | Fieldtypes | Sanitizer | Config | Notices | WireDatabasePDO | WireInput | string | mixed Get or inject a ProcessWire API variable

Protected Methods

Method Description
___callUnknown ( string $method, array $arguments ) : null | mixed If the above __call() resulted in no handler, this method is called.
_notice ( $text, integer $flags, string $name, string $class ) Record a Notice, internal use (contains the code for message, warning and error methods)

Method Details

_() public method

If not available, or if the current language is the native language, then it returns the text as is.
public _ ( string $text ) : string
$text string Text string to translate
return string

___callUnknown() protected method

This standard implementation just throws an exception. This is a template method, so the reason it exists is so that other classes can override and provide their own handler. Classes that provide their own handler should not do a parent::__callUnknown() unless they also fail.
protected ___callUnknown ( string $method, array $arguments ) : null | mixed
$method string Requested method name
$arguments array Arguments provided
return null | mixed

___changed() public method

Enables hooks to monitor changes to the object. Descending objects should trigger this via $this->changed('name') when a property they are tracking has changed.
public ___changed ( string $what, mixed $old = null, mixed $new = null )
$what string Name of property that changed
$old mixed Previous value before change
$new mixed New value

___log() public method

Message is saved to a log file in ProcessWire's logs path to a file with the same name as the class, converted to hyphenated lowercase.
public ___log ( string $str = '', array $options = [] ) : WireLog | null
$str string Text to log, or omit to just return the name of the log
$options array Optional extras to include: - url (string): URL to record the with the log entry (default=auto-detect) - name (string): Name of log to use (default=auto-detect)
return WireLog | null

___trackException() public method

It will log Exception to exceptions.txt log if 'exceptions' is in $config->logs. It will re-throw Exception if $config->allowExceptions == true. If additioanl $text is provided, it will be sent to $this->error when $fatal or $this->warning otherwise.
public ___trackException ( Exception $e, boolean | integer $severe = true, string | array | object | true $text = null )
$e Exception Exception object that was thrown
$severe boolean | integer Whether or not it should be considered severe (default=true)
$text string | array | object | true Additional details (optional). When provided, it will be sent to $this->error($text) if $severe==true, or $this->warning($text) if $severe==false. Specify boolean true to just sent the $e->getMessage() to $this->error() or $this->warning().

__call() public method

When a non-existant method is called, this checks to see if any hooks have been defined and sends the call to them. Hooks are defined by preceding the "hookable" method in a descending class with 3 underscores, like __myMethod(). When the API calls $myObject->myMethod(), it gets sent to $myObject->___myMethod() after any 'before' hooks have been called. Then after the ___myMethod() call, any "after" hooks are then called. "after" hooks have the opportunity to change the return value. Hooks can also be added for methods that don't actually exist in the class, allowing another class to add methods to this class. See the Wire::runHooks() method for the full implementation of hook calls.
public __call ( string $method, array $arguments ) : mixed
$method string
$arguments array
return mixed

__construct() public method

public __construct ( )

__debugInfo() public method

This is used when you print_r() an object instance.
public __debugInfo ( ) : array
return array

__get() public method

If not overridden, this is primarily used as a shortcut for the fuel() method. Descending classes may have their own __get() but must pass control to this one when they can't find something.
public __get ( string $name ) : mixed | null
$name string
return mixed | null

__toString() public method

Unless overridden, classes descending from Wire return their class name when typecast as a string
public __toString ( )

_n() public method

Perform a language translation with singular and plural versions
public _n ( string $textSingular, string $textPlural, integer $count ) : string
$textSingular string Singular version of text (when there is 1 item)
$textPlural string Plural version of text (when there are multiple items or 0 items)
$count integer Quantity used to determine whether singular or plural.
return string Translated text or original text if translation not available.

_notice() protected method

Record a Notice, internal use (contains the code for message, warning and error methods)
protected _notice ( $text, integer $flags, string $name, string $class )
$flags integer Flags bitmask
$name string Name of container
$class string Name of Notice class

_x() public method

Used when to text strings might be the same in English, but different in other languages.
public _x ( string $text, string $context ) : string
$text string Text for translation.
$context string Name of context
return string Translated text or original text if translation not available.

addHook() public method

Hookable method calls are methods preceded by three underscores. You may also specify a method that doesn't exist already in the class The hook method that you define may be part of a class or a globally scoped function. If you are hooking a procedural function, you may omit the $toObject and instead just call via: $this->addHook($method, 'function_name'); or $this->addHook($method, 'function_name', $options);
public addHook ( string $method, object | null | callable $toObject, string $toMethod = null, array $options = [] ) : string
$method string Method name to hook into, NOT including the three preceding underscores. May also be Class::Method for same result as using the fromClass option.
$toObject object | null | callable Object to call $toMethod from, Or null if $toMethod is a function outside of an object, Or function|callable if $toObject is not applicable or function is provided as a closure.
$toMethod string Method from $toObject, or function name to call on a hook event. Optional.
$options array See self::$defaultHookOptions at the beginning of this class. Optional.
return string A special Hook ID that should be retained if you need to remove the hook later

addHookAfter() public method

This is the same as calling addHook with the 'after' option set the $options array. If you are hooking a procedural function, you may omit the $toObject and instead just call via: $this->addHookAfter($method, 'function_name');
public addHookAfter ( string $method, object | null | callable $toObject, string $toMethod = null, array $options = [] ) : string
$method string Method name to hook into, NOT including the three preceding underscores May also be Class::Method for same result as using the fromClass option.
$toObject object | null | callable Object to call $toMethod from, Or null if $toMethod is a function outside of an object, Or function|callable if $toObject is not applicable or function is provided as a closure.
$toMethod string Method from $toObject, or function name to call on a hook event. Optional.
$options array See self::$defaultHookOptions at the beginning of this class. Optional.
return string A special Hook ID that should be retained if you need to remove the hook later

addHookBefore() public method

This is the same as calling addHook with the 'before' option set the $options array. If you are hooking a procedural function, you may omit the $toObject and instead just call via: $this->addHookBefore($method, 'function_name');
public addHookBefore ( string $method, object | null | callable $toObject, string $toMethod = null, array $options = [] ) : string
$method string Method name to hook into, NOT including the three preceding underscores May also be Class::Method for same result as using the fromClass option.
$toObject object | null | callable Object to call $toMethod from, Or null if $toMethod is a function outside of an object, Or function|callable if $toObject is not applicable or function is provided as a closure.
$toMethod string Method from $toObject, or function name to call on a hook event. Optional.
$options array See self::$defaultHookOptions at the beginning of this class. Optional.
return string A special Hook ID that should be retained if you need to remove the hook later

addHookProperty() public method

i.e. $obj->property; in addition to $obj->property(); This is the same as calling addHook with the 'type' option set to 'property' in the $options array. Note that descending classes that override __get must call getHook($property) and/or runHook($property). If you are hooking a procedural function, you may omit the $toObject and instead just call via: $this->addHookProperty($method, 'function_name');
public addHookProperty ( string $property, object | null | callable $toObject, string $toMethod = null, array $options = [] ) : string
$property string Method name to hook into, NOT including the three preceding underscores May also be Class::Method for same result as using the fromClass option.
$toObject object | null | callable Object to call $toMethod from, Or null if $toMethod is a function outside of an object, Or function|callable if $toObject is not applicable or function is provided as a closure.
$toMethod string Method from $toObject, or function name to call on a hook event. Optional.
$options array See self::$defaultHookOptions at the beginning of this class. Optional.
return string A special Hook ID that should be retained if you need to remove the hook later

className() public method

Note that it caches the class name in the $className object property to reduce overhead from calls to get_class().
public className ( array | null $options = null ) : string
$options array | null Optionally an option: - lowercase (bool): Specify true to make it return hyphenated lowercase version of class name
return string

error() public method

This method automatically identifies the error as coming from this class. Fatal errors should still throw a WireException (or class derived from it)
public error ( string | array | Wire $text, integer | boolean $flags )
$text string | array | Wire
$flags integer | boolean See Notices::flags or specify TRUE to have the error also logged to errors.txt

errors() public method

Return errors recorded by this object
public errors ( string | array $options = [] ) : Notices | string
$options string | array One or more of array elements or space separated string of: first: only first item will be returned (string) last: only last item will be returned (string) all: include all errors, including those beyond the scope of this object clear: clear out all items that are returned from this method array: return an array of strings rather than series of Notice objects. string: return a newline separated string rather than array/Notice objects.
return Notices | string Array of NoticeError error messages or string if last, first or str option was specified.

fuel() public method

Get the Fuel specified by $name or NULL if it doesn't exist
Deprecation: Fuel is now an internal-only keyword and this method will be going away. Use $this->wire(name) or $this->wire()->name instead
Deprecation:
public fuel ( string $name ) : mixed | null
$name string
return mixed | null

getAllFuel() public static method

Returns an iterable Fuel object of all Fuel currently loaded
Deprecation: This method will be going away. Use $this->wire() instead, or if static required use: Wire::getFuel() with no arguments
public static getAllFuel ( ) : Fuel
return Fuel

getChanges() public method

Return an array of properties that have changed while change tracking was on.
public getChanges ( boolean $getValues = false ) : array
$getValues boolean If true, then an associative array will be returned containing an array of previous values, oldest to newest.
return array

getFuel() public static method

Get the Fuel specified by $name or NULL if it doesn't exist
Deprecation:
public static getFuel ( string $name = '' ) : mixed | null
$name string
return mixed | null

getHooks() public method

Return all hooks associated with this class instance or method (if specified)
public getHooks ( string $method = '', integer $type ) : array
$method string Optional method that hooks will be limited to. Or specify '*' to return all hooks everywhere.
$type integer Type of hooks to return: 0=all, 1=local only, 2=static only
return array

hasHook() public method

Accomplishes the same thing as the static isHooked() method, but this is non-static, more accruate, and potentially slower than isHooked(). Less for optimization use, more for accuracy use. It checks for both static hooks and local hooks, but only accepts a method() or property name as an argument (i.e. no Class::something) since the class context is assumed from the current instance. Unlike isHooked() it also analyzes the instance's class parents for hooks, making it more accurate. As a result, this method works well for more than just optimization use. If checking for a hooked method, it should be in the form "method()". If checking for a hooked property, it should be in the form "property".
public hasHook ( string $method ) : boolean
$method string Method() or property name
return boolean

isChanged() public method

Applicable only for properties you are tracking while $trackChanges is true.
public isChanged ( string $what = '' ) : boolean
$what string Name of property, or if left blank, check if any properties have changed.
return boolean

isHooked() public static method

This is for optimization use. It does not distinguish about class instance. It only distinguishes about class if you provide a class with the $method argument (i.e. Class::). As a result, a true return value indicates something "might" be hooked, as opposed to be being definitely hooked. If checking for a hooked method, it should be in the form "Class::method()" or "method()". If checking for a hooked property, it should be in the form "Class::property" or "property".
public static isHooked ( string $method, Wire $instance = null ) : boolean
$method string Method or property name in one of the following formats: Class::method() Class::property method() property
$instance Wire Optional instance to check against (see hasHook method for details) Note that if specifying an $instance, you may not use the Class::method() or Class::property options for $method argument.
return boolean

message() public method

This method automatically identifies the message as coming from this class.
public message ( string | array | Wire $text, integer | boolean $flags )
$text string | array | Wire
$flags integer | boolean See Notices::flags or specify TRUE to have the message also logged to messages.txt

messages() public method

Return messages recorded by this object
public messages ( string | array $options = [] ) : Notices | string
$options string | array One or more of array elements or space separated string of: first: only first item will be returned (string) last: only last item will be returned (string) all: include all items of type (messages or errors) beyond the scope of this object clear: clear out all items that are returned from this method errors: returns errors rather than messages. warnings: returns warnings rather than messages. array: return an array of strings rather than series of Notice objects. string: return a newline separated string rather than array/Notice objects.
return Notices | string Array of NoticeError error messages or string if last, first or str option was specified.

removeHook() public method

To have a hook function remove itself within the hook function, say this is your hook function: function(HookEvent $event) { $event->removeHook(null); // remove self }
public removeHook ( string | null $hookId )
$hookId string | null

resetTrackChanges() public method

Clears out any tracked changes and turns change tracking ON or OFF
public resetTrackChanges ( boolean $trackChanges = true )
$trackChanges boolean True to turn change tracking ON, or false to turn OFF. Default of true is assumed.

runHooks() public method

Unlike __call, this method won't trigger an Exception if the hook and method don't exist. Instead it returns a result array containing information about the call.
public runHooks ( string $method, array $arguments, string $type = 'method' ) : array
$method string Method or property to run hooks for.
$arguments array Arguments passed to the method and hook.
$type string May be either 'method' or 'property', depending on the type of call. Default is 'method'.
return array Returns an array with the following information: [return] => The value returned from the hook or NULL if no value returned or hook didn't exist. [numHooksRun] => The number of hooks that were actually run. [methodExists] => Did the hook method exist as a real method in the class? (i.e. with 3 underscores ___method). [replace] => Set by the hook at runtime if it wants to prevent execution of the original hooked method.

setFuel() public static method

Add fuel to all classes descending from Wire
Deprecation: Use $this->wire($name, $value, $lock) instead.
public static setFuel ( string $name, mixed $value, boolean $lock = false )
$name string
$value mixed
$lock boolean Whether the API value should be locked (non-overwritable)

setTrackChanges() public method

Turn change tracking ON or OFF
public setTrackChanges ( boolean | integer $trackChanges = true )
$trackChanges boolean | integer True to turn on, false to turn off. Integer to specify bitmask.

trackChange() public method

The change will only be recorded if $this->trackChanges is a positive value.
public trackChange ( string $what, mixed $old = null, mixed $new = null )
$what string Name of property that changed
$old mixed Previous value before change
$new mixed New value

trackChanges() public method

Returns true if change tracking is on, or false if it's not.
public trackChanges ( boolean $getMode = false ) : boolean | integer
$getMode boolean When true, the track changes mode bitmask will be returned rather than a boolean
return boolean | integer

untrackChange() public method

Untrack a change to a property in this object
public untrackChange ( string $what )
$what string Name of property that you want to remove it's change being tracked

useFuel() public method

If so, you can do things like $this->apivar. If not, then you'd have to do $this->wire('apivar'). If you specify a value, it will set the value of useFuel to true or false. If you don't specify a value, the current value will be returned. Local fuel scope should be disabled in classes where it might cause any conflict with class vars.
public useFuel ( boolean $useFuel = null ) : boolean
$useFuel boolean Optional boolean to turn it on or off.
return boolean Current value of $useFuel

warning() public method

This method automatically identifies the warning as coming from this class.
public warning ( string | array | Wire $text, integer | boolean $flags )
$text string | array | Wire
$flags integer | boolean See Notices::flags or specify TRUE to have the error also logged to errors.txt

warnings() public method

Return warnings recorded by this object
public warnings ( string | array $options = [] ) : Notices | string
$options string | array One or more of array elements or space separated string of: first: only first item will be returned (string) last: only last item will be returned (string) all: include all warnings, including those beyond the scope of this object clear: clear out all items that are returned from this method array: return an array of strings rather than series of Notice objects. string: return a newline separated string rather than array/Notice objects.
return Notices | string Array of NoticeError error messages or string if last, first or str option was specified.

wire() public method

1. As a getter (option 1): ========================== Usage: $this->wire('name'); // name is an API variable name If 'name' does not exist, a WireException will be thrown. Specify '*' or 'all' for name to retrieve all API vars (as a Fuel object) 2. As a getter (option 2): ========================== Usage: $this->wire()->name; // name is an API variable name Null will be returned if API var does not exist (no Exception thrown). 3. As a setter: =============== $this->wire('name', $value); $this->wire('name', $value, true); // lock the API variable so nothing else can overwrite it $this->wire()->set('name', $value); $this->wire()->set('name', $value, true); // lock the API variable so nothing else can overwrite it 4. As a dependency injector (PW 3.0 only) ========================================= $this->wire(new Page()); When creating a new object, this makes it inject the current PW instance into that object.
public wire ( string | object $name = '', null | mixed $value = null, boolean $lock = false ) : ProcessWire | Wire | Session | Page | Pages | Modules | User | Users | Roles | Permissions | Templates | Fields | Fieldtypes | Sanitizer | Config | Notices | WireDatabasePDO | WireInput | string | mixed
$name string | object Name of API variable to retrieve, set, or omit to retrieve the master ProcessWire object
$value null | mixed Value to set if using this as a setter, otherwise omit.
$lock boolean When using as a setter, specify true if you want to lock the value from future changes (default=false)
return ProcessWire | Wire | Session | Page | Pages | Modules | User | Users | Roles | Permissions | Templates | Fields | Fieldtypes | Sanitizer | Config | Notices | WireDatabasePDO | WireInput | string | mixed

Property Details

$_notices protected_oe property

***************************************************************************************************** NOTICES AND LOGS
protected $_notices

$allLocalHooks public_oe static_oe property

Cache of all local hooks combined, for debugging purposes
public static $allLocalHooks

$defaultHookOptions protected_oe static_oe property

- type: may be either 'method' or 'property'. If property, then it will respond to $obj->property rather than $obj->method(). - before: execute the hook before the method call? Not applicable if 'type' is 'property'. - after: execute the hook after the method call? (allows modification of return value). Not applicable if 'type' is 'property'. - priority: a number determining the priority of a hook, where lower numbers are executed before higher numbers. - allInstances: attach the hook to all instances of this object? (store in staticHooks rather than localHooks). Set automatically, but you may still use in some instances. - fromClass: the name of the class containing the hooked method, if not the object where addHook was executed. Set automatically, but you may still use in some instances. - argMatch: array of Selectors objects where the indexed argument (n) to the hooked method must match, order to execute hook. - objMatch: Selectors object that the current object must match in order to execute hook
protected static $defaultHookOptions

$fuel protected_oe static_oe property

Fuel holds references to other ProcessWire system objects. It is an instance of the Fuel class.
Deprecation:
protected static Fuel|null $fuel
return Fuel | null

$hookMethodCache protected_oe static_oe property

Hooked methods end with '()' while hooked properties don't. This does not distinguish which instance it was added to or whether it was removed. But will use keys in the form 'fromClass::method' (with value 'method') in cases where a fromClass was specified. This cache exists primarily to gain some speed in our __get and __call methods.
protected static $hookMethodCache

$localHooks protected_oe property

Hooks that are local to this instance of the class only.
protected $localHooks

$staticHooks protected_oe static_oe property

This array holds references to those static hooks, and is shared among all classes descending from Wire. It is for internal use only. See also self::$defaultHookOptions[allInstances].
protected static $staticHooks

$useFuel protected_oe property

Whether this class may use fuel variables in local scope, like $this->item
protected bool $useFuel
return boolean