Creating Events

Creating an event simply sets a callback to be invoked if and only if during the execution of the current program such an event is triggered. This is useful if you require notification of certain actions throughout your application.

Registering an Event

Registering an event will allow your callback to be notified when such an event is triggered. Any controller or model that inherits from AppController or AppModel will already have access to the event handler and can immediately begin registering events.

$this->Events->register("EventName", array($this, "callbackMethod"));

In the above example, when the "EventName" event is triggered the "callbackMethod" will be invoked on the object that registered the event. If you're working from a separate location that doesn't inherit from AppController or AppModel, you can load the Event handler manually.

// Load the Event handler
Loader::load(COMPONENTDIR . "events" . DS . "events.php");
$this->Events = new Events();

Triggering an Event

Triggering an event invokes all callbacks that have been registered for that event. To trigger the "EventName" event invoke the Events::trigger() method and pass in an instance of the EventObject that will be passed to each callback.

$event = new EventObject("EventName", array("square", "pink")); 
$this->Events->trigger($event);

Here's a complete example that will output "square pink".

<?php
class MyController extends AppController {

    public function index() {
        $this->Events->register("EventName", array($this, "callbackMethod"));
        $event = new EventObject("EventName", array("square", "pink")); 
        $this->Events->trigger($event);
        return false; // don't render a view
    }

    public function callbackMethod(EventObject $event) {
        $params = $event->getParams();
        echo $params[0] . " " . $params[1];
    }
}
?>

Returning Data From an Event

The EventObject passed to each event callback contains setters and getters for both parameters (as seen above when Triggering an Event), and return values. Expanding on the example above, we can set our return value using the EventObject::setReturnVal() method. This will output "square".

<?php
class MyController extends AppController {
    public function index() {
        $this->Events->register("EventName", array($this, "callbackMethod"));
        $event = new EventObject("EventName", array("square", "pink")); 
        $event = $this->Events->trigger($event);
        echo $event->getReturnVal();
        return false; // don't render a view
    }
    
    public function callbackMethod(EventObject $event) {
        $params = $event->getParams();
        $event->setReturnVal($params[0]);
    }
}
?>