symfony Symfony Overview of symfony 1.1 event dispatcher

As you may now by now, Symfony 1.1 introduces a new powerfull event dispatcher inspired by Apple Cocoa's NotificationCenter. Basically, it allows any entity to "listen" to events, and get a call on the registered callback if this event ever happens.

Symfony 1.1 provides some default events you can listen to, but of course you can create your own events if you need.

Listen to an event

To listen to an event, you need to use the "connect" method on the event dispatcher instance. The first parameter is the event name, and the second is a PHP callable that will get called if the event happens.

<?php
$dispatcher->connect('user.change_culture', array($this, 'listenToChangeCultureEvent'));

Create a custom event

To use the dispatcher for your own needs, you just need to define your event name in your project specifications, and send notifications to it. Depending on the behaviour needed, three options are offered:

Simple notifications

The simpliest way is to notify all listeners with the ->notify() method.

<?php
$dispatcher->notify(new sfEvent($this, 'my.super.cool.event'));

Notifications until something

Sometimes, you prefer to notify all listeners until one says "Ok guys, I handled this one. Don't worry about it anymore".

<?php
$dispatcher->notifyUntil(new sfEvent($this, 'my.super.cool.event'));

The first listener that will return non-false value will stop the event chain.

Filtering notifications

The last notifying method is called filtering. You set this up when you want to permit anything to act as a filter on something, meaning any listener can modify a source object.

<?php
$dispatcher->filter(new sfEvent($this, 'my.super.cool.event'), $objectToFilter);

Every listener must return the filtered value (or the original object if nothing was done) to pass to the next listener.

Practical use: Register routes in your plugins

One of the first practical applications that came to me was the new way of registering routes in plugins. In symfony 1.0, a coincidence made possible to use the routing in a plugin's config.php but that's not possible anymore in symfony 1.1, so you have to use the event dispatcher. To accomplish this, we're going to set up a routing.load_configuration listener in the plugin's config.php:

<?php
$this->dispatcher->connect('routing.load_configuration', array('myPluginRouting', 'listenToRoutingLoadConfigurationEvent'));

Then you just need to create the callback class/method:

<?php
class myPluginRouting
{
  /**
   * Listens to the routing.load_configuration event.
   *
   * @param sfEvent An sfEvent instance
   */
  static public function listenToRoutingLoadConfigurationEvent(sfEvent $event)
  {
    $r = $event->getSubject();

    // preprend our routes
    $r->prependRoute('my_route', '/my_plugin/:action', array('module' => 'myPluginAdministrationInterface'));
  }
}

Here we go :-D