Events System¶

Global Event Manager¶

In addition to instance level event managers, CakePHP provides a global event manager that allows you to listen to any event fired in an application. This is useful when attaching listeners to a specific instance might be cumbersome or difficult. The global manager is a singleton instance of Cake\Event\EventManager. Listeners attached to the global dispatcher will be fired before instance listeners at the same priority. You can access the global manager using a static method:

// In any configuration file or piece of code that executes before the event
use Cake\Event\EventManager;

EventManager::instance()->on(
    'Order.afterPlace',
    $aCallback
);

One important thing you should consider is that there are events that will be triggered having the same name but different subjects, so checking it in the event object is usually required in any function that gets attached globally in order to prevent some bugs. Remember that with the flexibility of using the global manager, some additional complexity is incurred.

Cake\Event\EventManager::dispatch() method accepts the event object as an argument and notifies all listener and callbacks passing this object along. The listeners will handle all the extra logic around the afterPlace event, you can log the time, send emails, update user statistics possibly in separate objects and even delegating it to offline tasks if you have the need.

Tracking Events¶

To keep a list of events that are fired on a particular EventManager, you can enable event tracking. To do so, simply attach an Cake\Event\EventList to the manager:

EventManager::instance()->setEventList(new EventList());

After firing an event on the manager, you can retrieve it from the event list:

$eventsFired = EventManager::instance()->getEventList();
$firstEvent = $eventsFired[0];

Tracking can be disabled by removing the event list or calling Cake\Event\EventList::trackEvents(false).

Registering Anonymous Listeners¶

While event listener objects are generally a better way to implement listeners, you can also bind any callable as an event listener. For example if we wanted to put any orders into the log files, we could use a simple anonymous function to do so:

use Cake\Log\Log;

// From within a controller or during application bootstrap.
$this->Orders->getEventManager()->on('Order.afterPlace', function ($event) {
    Log::write(
        'info',
        'A new order was placed with id: ' . $event->getSubject()->id
    );
});

In addition to anonymous functions you can use any other callable type that PHP supports:

$events = [
    'email-sending' => 'EmailSender::sendBuyEmail',
    'inventory' => [$this->InventoryManager, 'decrement'],
];
foreach ($events as $callable) {
    $eventManager->on('Order.afterPlace', $callable);
}

When working with plugins that don’t trigger specific events, you can leverage event listeners on the default events. Lets take an example ‘UserFeedback’ plugin which handles feedback forms from users. From your application you would like to know when a Feedback record has been saved and ultimately act on it. You can listen to the global Model.afterSave event. However, you can take a more direct approach and only listen to the event you really need:

// You can create the following before the
// save operation, ie. config/bootstrap.php
use Cake\ORM\TableRegistry;
// If sending emails
use Cake\Mailer\Email;

TableRegistry::getTableLocator()->get('ThirdPartyPlugin.Feedbacks')
    ->getEventManager()
    ->on('Model.afterSave', function($event, $entity)
    {
        // For example we can send an email to the admin
        // Prior to 3.4 use from()/to()/subject() methods
        $email = new Email('default');
        $email->setFrom(['[email protected]' => 'Your Site'])
            ->setTo('[email protected]')
            ->setSubject('New Feedback - Your Site')
            ->send('Body of message');
    });

You can use this same approach to bind listener objects.

Interacting with Existing Listeners¶

Assuming several event listeners have been registered the presence or absence of a particular event pattern can be used as the basis of some action.:

// Attach listeners to EventManager.
$this->getEventManager()->on('User.Registration', [$this, 'userRegistration']);
$this->getEventManager()->on('User.Verification', [$this, 'userVerification']);
$this->getEventManager()->on('User.Authorization', [$this, 'userAuthorization']);

// Somewhere else in your application.
$events = $this->getEventManager()->matchingListeners('Verification');
if (!empty($events)) {
    // Perform logic related to presence of 'Verification' event listener.
    // For example removing the listener if present.
    $this->getEventManager()->off('User.Verification');
} else {
    // Perform logic related to absence of 'Verification' event listener
}

Establishing Priorities¶

In some cases you might want to control the order that listeners are invoked. For instance, if we go back to our user statistics example. It would be ideal if this listener was called at the end of the stack. By calling it at the end of the listener stack, we can ensure that the event was not cancelled, and that no other listeners raised exceptions. We can also get the final state of the objects in the case that other listeners have modified the subject or event object.

Priorities are defined as an integer when adding a listener. The higher the number, the later the method will be fired. The default priority for all listeners is 10. If you need your method to be run earlier, using any value below this default will work. On the other hand if you desire to run the callback after the others, using a number above 10 will do.

If two callbacks happen to have the same priority value, they will be executed with a the order they were attached. You set priorities using the on() method for callbacks, and declaring it in the implementedEvents() function for event listeners:

// Setting priority for a callback
$callback = [$this, 'doSomething'];
$this->getEventManager()->on(
    'Order.afterPlace',
    ['priority' => 2],
    $callback
);

// Setting priority for a listener
class UserStatistic implements EventListenerInterface
{
    public function implementedEvents()
    {
        return [
            'Order.afterPlace' => [
                'callable' => 'updateBuyStatistic',
                'priority' => 100
            ],
        ];
    }
}

As you see, the main difference for EventListener objects is that you need to use an array for specifying the callable method and the priority preference. The callable key is a special array entry that the manager will read to know what function in the class it should be calling.

Getting Event Data as Function Parameters¶

When events have data provided in their constructor, the provided data is converted into arguments for the listeners. An example from the View layer is the afterRender callback:

$this->getEventManager()
    ->dispatch(new Event('View.afterRender', $this, ['view' => $viewFileName]));

The listeners of the View.afterRender callback should have the following signature:

function (Event $event, $viewFileName)

Each value provided to the Event constructor will be converted into function parameters in the order they appear in the data array. If you use an associative array, the result of array_values will determine the function argument order.

Stopping Events¶

Much like DOM events, you may want to stop an event to prevent additional listeners from being notified. You can see this in action during model callbacks (e.g. beforeSave) in which it is possible to stop the saving operation if the code detects it cannot proceed any further.

In order to stop events you can either return false in your callbacks or call the stopPropagation() method on the event object:

public function doSomething($event)
{
    // ...
    return false; // Stops the event
}

public function updateBuyStatistic($event)
{
    // ...
    $event->stopPropagation();
}

Stopping an event will prevent any additional callbacks from being called. Additionally the code triggering the event may behave differently based on the event being stopped or not. Generally it does not make sense to stop ‘after’ events, but stopping ‘before’ events is often used to prevent the entire operation from occurring.

To check if an event was stopped, you call the isStopped() method in the event object:

public function place($order)
{
    $event = new Event('Order.beforePlace', $this, ['order' => $order]);
    $this->getEventManager()->dispatch($event);
    if ($event->isStopped()) {
        return false;
    }
    if ($this->Orders->save($order)) {
        // ...
    }
    // ...
}

In the previous example the order would not get saved if the event is stopped during the beforePlace process.

Getting Event Results¶

Every time a callback returns a non-null non-false value, it gets stored in the $result property of the event object. This is useful when you want to allow callbacks to modify the event execution. Let’s take again our beforePlace example and let callbacks modify the $order data.

Event results can be altered either using the event object result property directly or returning the value in the callback itself:

// A listener callback
public function doSomething($event)
{
    // ...
    $alteredData = $event->getData('order') + $moreData;
    return $alteredData;
}

// Another listener callback
public function doSomethingElse($event)
{
    // ...
    $event->setResult(['order' => $alteredData] + $this->result());
}

// Using the event result
public function place($order)
{
    $event = new Event('Order.beforePlace', $this, ['order' => $order]);
    $this->getEventManager()->dispatch($event);
    if (!empty($event->getResult()['order'])) {
        $order = $event->getResult()['order'];
    }
    if ($this->Orders->save($order)) {
        // ...
    }
    // ...
}

It is possible to alter any event object property and have the new data passed to the next callback. In most of the cases, providing objects as event data or result and directly altering the object is the best solution as the reference is kept the same and modifications are shared across all callback calls.

Removing Callbacks and Listeners¶

If for any reason you want to remove any callback from the event manager just call the Cake\Event\EventManager::off() method using as arguments the first two parameters you used for attaching it:

// Attaching a function
$this->getEventManager()->on('My.event', [$this, 'doSomething']);

// Detaching the function
$this->getEventManager()->off('My.event', [$this, 'doSomething']);

// Attaching an anonymous function.
$myFunction = function ($event) { ... };
$this->getEventManager()->on('My.event', $myFunction);

// Detaching the anonymous function
$this->getEventManager()->off('My.event', $myFunction);

// Adding a EventListener
$listener = new MyEventLister();
$this->getEventManager()->on($listener);

// Detaching a single event key from a listener
$this->getEventManager()->off('My.event', $listener);

// Detaching all callbacks implemented by a listener
$this->getEventManager()->off($listener);

Events are a great way of separating concerns in your application and make classes both cohesive and decoupled from each other. Events can be utilized to de-couple application code and make extensible plugins.

Keep in mind that with great power comes great responsibility. Using too many events can make debugging harder and require additional integration testing.