---
title: Callbacks
---

# Callbacks

<div class="documentation__toc"></div>

@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

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$trigger

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The trigger for the callback.

</td>

</tr>

<tr>

<td>

$callback

</td>

<td>

true

</td>

<td>

string|Closure

</td>

<td>

none

</td>

<td>

The callback logic or callable string.

</td>

</tr>

</tbody>

</table>

#### 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](#core-concepts/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

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$trigger

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The trigger for the callback.

</td>

</tr>

<tr>

<td>

$callback

</td>

<td>

true

</td>

<td>

string|Closure

</td>

<td>

none

</td>

<td>

The callback logic or callable string.

</td>

</tr>

</tbody>

</table>

#### 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

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$trigger

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The trigger for the callback to fire.

</td>

</tr>

<tr>

<td>

$parameters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

Parameters to pass to the callback.

</td>

</tr>

</tbody>

</table>

#### 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

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$trigger

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The trigger for the callback to existance of.

</td>

</tr>

</tbody>

</table>

#### Example

    $callable->hasCallback('querying');

### FiresCallbacks::hasListener()

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

#### Returns: `boolean`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$trigger

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The trigger for the listener to existance of.

</td>

</tr>

</tbody>

</table>

#### 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'

