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

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

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

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

Example

$callable->hasCallback('querying');

FiresCallbacks::hasListener()

The hasListener method returns whether or not the class has a listener.

Returns: boolean

Arguments

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'