Callbacks
@TODO review
Introduction
A callback
is a type of event in PyroCMS. Callbacks differ from events in that the scope is relative to an instance of an object. Whereas events are broadcast across the entire application.
Callbacks consist of a trigger
and the callback
.
Triggers
The trigger
is what causes the callback
to fire.
Callbacks
The callback
is the callable string or Closure
that is fired when the trigger
is.. triggered.
Listeners
Listeners
are the same as callbacks but for one major difference; they apply to all instances of the class. Whereas standard callbacks
only apply to the instance they are registered on.
Basic Usage
Use the \Anomaly\Streams\Platform\Traits\FiresCallbacks
trait in your class to get started.
FiresCallbacks::on()
The on
method registers a simple callback
.
Returns: $this
Arguments
Key | Required | Type | Default | Description |
---|---|---|---|---|
$trigger |
true |
string |
none |
The trigger for the callback. |
$callback |
true |
string|Closure |
none |
The callback logic or callable string. |
Example
// Example of using a callable string
$callable->on('before_starting', 'App\Example@test');
$callable->beforeStarting();
// Example of using a Closure
$callable->on('querying', function(Builder $query) {
$query->where('modifier_id', $this->example->getId());
});
$callable->sayHello('Ryan!'); // Hello Ryan!
Callbacks are called with the Service Container so all dependencies are resolved automatically.{.notice}
FiresCallbacks::listen()
The listen
method registers callbacks very similar to on
except the callback
applies to all instances of the class.
Returns: $this
Arguments
Key | Required | Type | Default | Description |
---|---|---|---|---|
$trigger |
true |
string |
none |
The trigger for the callback. |
$callback |
true |
string|Closure |
none |
The callback logic or callable string. |
Example
// Example of using a callable string
$callable->on('before_starting', 'App\Example@test');
$callable->beforeStarting();
// Example of using a Closure
$callable->on('say_hello', function($name) {
return 'Hello ' . $name;
});
$callable->sayHello('Ryan!'); // Hello Ryan!
FiresCallbacks::fire()
The fire
method does just as it's name suggests. It fires a callback
.
Returns: mixed
Arguments
Key | Required | Type | Default | Description |
---|---|---|---|---|
$trigger |
true |
string |
none |
The trigger for the callback to fire. |
$parameters |
false |
array |
null |
Parameters to pass to the callback. |
Example
$callable->fire('querying', compact('builder', 'query'));
FiresCallbacks::hasCallback()
The hasCallback
method returns whether or not a callback exists on the instance.
Returns: boolean
Arguments
Key | Required | Type | Default | Description |
---|---|---|---|---|
$trigger |
true |
string |
none |
The trigger for the callback to existance of. |
Example
$callable->hasCallback('querying');
FiresCallbacks::hasListener()
The hasListener
method returns whether or not the class has a listener.
Returns: boolean
Arguments
Key | Required | Type | Default | Description |
---|---|---|---|---|
$trigger |
true |
string |
none |
The trigger for the listener to existance of. |
Example
$this->hasListener('querying');
Method Handlers
Method handlers are specific methods in a class that are named after a callback trigger
. If the trigger
is before_querying
the handler method will be onBeforeQuerying
.
// First register the callback.
$callable->on('querying', function(Builder $query) {
$query->where('modifier_id', $this->example->getId());
});
// Now fire using the handler method.
$callable->onQuerying(compact('builder'));
Self Handling Callbacks
If using a callable string like Example\Test@method
without an @method
then @handle
will be assumed.
$callable->on('querying', \Example\Test::class); // Assumes 'Example\Test@handle'