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 CakeEventManager. When an event is dispatched, it will be dispatched both to the global and to the instance level listeners in priority order. You can access the global manager using a static method:

// In any configuration file or piece of code that executes before the event
App::uses('CakeEventManager', 'Event');
CakeEventManager::instance()->attach(
    $aCallback,
    'Model.Order.afterPlace'
);

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.

Registering Global Listeners¶

As shown in the example above, event listeners are conventionally placed in app/Lib/Event. Following this convention allows you to easily locate your listener classes. It is also recommended that you attach global listeners during your application bootstrap process:

// In app/Config/bootstrap.php

// Load the global event listeners.
require_once APP . 'Config' . DS . 'events.php'

An example events bootstrap file for our cart application could look like:

// In app/Config/events.php

// Load event listeners
App::uses('UserStatistic', 'Lib/Event');
App::uses('ProductStatistic', 'Lib/Event');
App::uses('CakeEventManager', 'Event');

// Attach listeners.
CakeEventManager::instance()->attach(new UserStatistic());
CakeEventManager::instance()->attach(new ProductStatistic());

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:

// Anonymous functions require PHP 5.3+
$this->Order->getEventManager()->attach(function($event) {
    CakeLog::write(
        'info',
        'A new order was placed with id: ' . $event->subject()->id
    );
}, 'Model.Order.afterPlace');

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

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

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 canceled, 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 attach method for callbacks, and declaring it in the implementedEvents function for event listeners:

// Setting priority for a callback
$callback = array($this, 'doSomething');
$this->getEventManager()->attach(
    $callback,
    'Model.Order.afterPlace',
    array('priority' => 2)
);

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

As you see, the main difference for CakeEventListener objects is that you need to use an array for specifying the callable method and the priority preference. The callable key is an 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¶

By default listeners receive the event object as their only parameter. If you are building an event that doesn’t need access to the event object you may want to have the event data passed as function parameters. This feature is used by the callbacks CakePHP fires in order to preserve backwards compatibility.

If you want to enable this feature, you have to add the passParams option to the third argument of the attach method, or declare it in the implementedEvents returned array similar to what you do with priorities:

// Enabling passed parameters mode for an anonymous listener
$callback = array($this, 'doSomething');
$this->getEventManager()->attach(
    $callback,
    'Model.Order.afterPlace',
    array('passParams' => true)
);

// Enabling passed parameters mode for a listener
class UserStatistic implements CakeEventListener {
    public function implementedEvents() {
        return array(
            'Model.Order.afterPlace' => array(
                'callable' => 'updateBuyStatistic',
                'passParams' => true
            ),
        );
    }

    public function updateBuyStatistic($orderData) {
        // ...
    }
}

In the above code the doSomething function and updateBuyStatistic method will receive $orderData instead of the $event object. This is so, because in our previous example we trigger the Model.Order.afterPlace event with some data:

$event = new CakeEvent('Model.Order.afterPlace', $this, array(
    'order' => $order
));
$this->getEventManager()->dispatch($event);

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 CakeEvent(
        'Model.Order.beforePlace',
        $this, array('order' => $order)
    );
    $this->getEventManager()->dispatch($event);
    if ($event->isStopped()) {
        return false;
    }
    if ($this->Order->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 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->data['order'] + $moreData;
    return $alteredData;
}

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

// Using the event result
public function place($order) {
    $event = new CakeEvent(
        'Model.Order.beforePlace',
        $this, array('order' => $order)
    );
    $this->getEventManager()->dispatch($event);
    if (!empty($event->result['order'])) {
        $order = $event->result['order'];
    }
    if ($this->Order->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 CakeEventManager::detach() method using as arguments the first two params you used for attaching it:

// Attaching a function
$this->getEventManager()->attach(array($this, 'doSomething'), 'My.event');

// Detaching the function
$this->getEventManager()->detach(array($this, 'doSomething'), 'My.event');

// Attaching an anonymous function (PHP 5.3+ only);
$myFunction = function($event) { ... };
$this->getEventManager()->attach($myFunction, 'My.event');

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

// Attaching a CakeEventListener
$listener = new MyEventListener();
$this->getEventManager()->attach($listener);

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

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