Class \Prado\TEventHandler
This class is a helper class for passing specific data along with an event handler. Normal event handlers only have a sender and parameter, but under a TEventHandler there is a third parameter in the event handler method for data. This class is invokable and will pass invoked method arguments forward to the managed handler with the specified data.
A TEventHandler handler method would be implemented as such:
$handler = new TEventHandler([$object, 'myHandler'], ['key' => 'data']);
$handler($sender, $param); // <- invokable
$component->attachEventHandler('onMyEvent', $handler, $priority);
// In the $object class:
public function myHandler(object $sender, mixed $param, mixed $data = null): mixed
{
// $data === ['key' => 'data']
....
}
In this instance, $data is default to null so it can be called on a raised attached event without TEventHandler. If you will only have a your handler use TEventHandler, then $data can be required (without the null default).
There are several ways to access the event handler (callable). getHandler will return the event handler and can be requested to return the callable as WeakReference.
The event handler can be accessed by ArrayAccess as well. For example:
$handler = new TEventHandler('TMyClass::myStaticHandler', ['data' => 2, ...]);
$handler[null] === 'TMyClass::myStaticHandler' === $handler->getHandler();
$handler[0] === 'TMyClass::myStaticHandler';
$handler[1] === null
$handler[2] === ['data' => 2, ...] === $handler->getData();
$handler = new TEventHandler([$behavior, 'myHandler'], ['data' => 3, ...]);
$handler[null] === [$behavior, 'myHandler'] === $handler->getHandler();
$handler[0] === $behavior;
$handler[1] === 'myHandler';
$handler[2] === ['data' => 3, ...] === $handler->getData();
// Add the handler to the event at priority 12 (the default is 10)
$component->attachEventHandler('onMyEvent', $handler, 12);
PRADO event handler objects are stored as WeakReference to improve PHP garbage collection. To enable this functionality, TEventHandler holds its callable object as WeakReference and re-references the callable handler object when used.
The only exceptions to conversion into WeakReference are Closure and IWeakRetainable. Closure and IWeakRetainable are retained without WeakReference conversion because they might be the only instance in the application. Holding these instances directly will properly increment their PHP use counter to be retained.
hasWeakObject returns if there is an object being held as WeakReference.
When the TEventHandler \Prado\getData is an array, and the 3rd parameter
$data of \Prado__invoke is also an array, an array_replace (with the
function parameter array taking precedence) will combine the data.
In nesting TEventHandlers, a base TEventHandler, pointing to a callable, can be instanced with core data. Children TEventHandler[s] can point to the parent TEventHandler and override specific data items in the \Prado\getData array with its own (array) data items. This only works if the Data is an array otherwise the children will override the parent TEventHandler data.
Class hierarchy
- \Prado\TEventHandler implements IPriorityProperty, IWeakRetainable, ArrayAccess, Countable uses TPriorityPropertyTrait
Since: 4.3.0
public
|
__construct(mixed $handler[, mixed $data = null ]) : mixed
Constructs a new TEventHandler and initializes the Event Handler and Data.
|
public
|
__invoke([mixed $sender = null ][, mixed $param = null ][, null|mixed $data = null ], array<string|int, mixed> ...$argv) : mixed
This calls the handler with the specified data. If no $data is specified then
TEventHandler injects its own data for the event handler. When $data is an array
and the TEventHandler data is an array, the data is combined by `array_replace`,
with the function input array data taking precedence over TEventHandler data.
This allows TEventHandlers to be nested, with children taking precedence. |
public
|
count() : int
Returns the number of items in the managed event handler (with data).
This method is required by \Countable interface. |
public
|
getCount() : int
There are 3 items when the handler is an array, and 2 items when the handler
is an invokable object or string.
|
public
|
getData([bool $withHandlerData = false ]) : mixed
Returns the data associated with the managed event handler. By passing true to
$withHandlerData, this will combine the data from nested TEventHandlers when the
data is in array format. The children data take precedence in the combining
of data.
|
public
|
getHandler([bool $weak = false ]) : null|array<string|int, mixed>|object|string
Gets the handler being managed. The WeakReference version of the handler can
be retrieved by passing true to the $weak parameter. When there are nested
TEventHandlers, this will return the next TEventHandler as an invokable and will
not link to the last and actual callable handler.
|
public
|
getHandlerObject([bool $weak = false ]) : object|null
If there is an object referenced in the callable, this method returns the object.
By default, the WeakReference is re-referenced. The WeakReference can be returned by passing true for $weak. This will return Closure and IWeakRetainable objects without any WeakReference because they are exempt from conversion into WeakReference. When TEventHandlers are nested, this returns the last and actual callable object. |
public
|
hasHandler() : bool
This checks if the managed handler is still valid. When TEventHandler are nested,
this returns if the last and actual handler is still valid (from WeakReference).
|
public
|
hasWeakObject() : bool
Does the object contain any WeakReference objects? When there are nested TEventHandler
this will return the last and actual data from the actual callable.
|
public
|
isSameHandler(mixed $item[, bool $weak = false ]) : bool
This methods checks if the item is the same as the handler. When TEventHandler
are nested, we check the nested TEventHandler for isSameHandler.
|
public
|
offsetExists(mixed $offset) : bool
These values exist: null (the handler), 0, 2, and conditionally 1 on the handler
being an array.
|
public
|
offsetGet(mixed $offset) : mixed
This is a convenience method for getting the data of the TEventHandler.
|
public
|
offsetSet(mixed $offset, mixed $value) : void
This is a convenience method for setting the data of the managed event handler.
This cannot set the event handler but can set the data.
|
public
|
offsetUnset(mixed $offset) : void
This is a convenience method for resetting the data to null. The Handler cannot
be unset. However, the data can be unset. The only valid index for unsetting
the handler data is '2'.
|
public
|
getPriority, setPriority, _priorityItemZappableSleepProps |