Events¶

When an event is dispatched, it's identified by a unique name (e.g. kernel.response), which any number of listeners might be listening to. An Event instance is also created and passed to all of the listeners. As you'll see later, the Event object itself often contains data about the event being dispatched.

The Dispatcher¶

The dispatcher is the central object of the event dispatcher system. In general, a single dispatcher is created, which maintains a registry of listeners. When an event is dispatched via the dispatcher, it notifies all listeners registered with that event:

1
2
3

use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();

Connecting Listeners¶

To take advantage of an existing event, you need to connect a listener to the dispatcher so that it can be notified when the event is dispatched. A call to the dispatcher addListener() method associates any valid PHP callable to an event:

1
2

$listener = new AcmeListener();
$dispatcher->addListener('foo.action', array($listener, 'onFooAction'));

The addListener() method takes up to three arguments:

• The event name (string) that this listener wants to listen to;
• A PHP callable that will be notified when an event is thrown that it listens to;
• An optional priority integer (higher equals more important) that determines when a listener is triggered versus other listeners (defaults to 0). If two listeners have the same priority, they are executed in the order that they were added to the dispatcher.

1
2
3
4
5

use Symfony\Component\EventDispatcher\Event;

$dispatcher->addListener('foo.action', function (Event $event) {
    // will be executed when the foo.action event is dispatched
});

Once a listener is registered with the dispatcher, it waits until the event is notified. In the above example, when the foo.action event is dispatched, the dispatcher calls the AcmeListener::onFooAction method and passes the Event object as the single argument:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use Symfony\Component\EventDispatcher\Event;

class AcmeListener
{
    // ...

    public function onFooAction(Event $event)
    {
        // ... do something
    }
}

In many cases, a special Event subclass that's specific to the given event is passed to the listener. This gives the listener access to special information about the event. Check the documentation or implementation of each event to determine the exact Symfony\Component\EventDispatcher\Event instance that's being passed. For example, the kernel.event event passes an instance of Symfony\Component\HttpKernel\Event\FilterResponseEvent:

1
2
3
4
5
6
7
8
9

use Symfony\Component\HttpKernel\Event\FilterResponseEvent;

public function onKernelResponse(FilterResponseEvent $event)
{
    $response = $event->getResponse();
    $request = $event->getRequest();

    // ...
}

Creating and Dispatching an Event¶

In addition to registering listeners with existing events, you can create and dispatch your own events. This is useful when creating third-party libraries and also when you want to keep different components of your own system flexible and decoupled.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

namespace Acme\StoreBundle;

final class StoreEvents
{
    /**
     * The store.order event is thrown each time an order is created
     * in the system.
     *
     * The event listener receives an
     * Acme\StoreBundle\Event\FilterOrderEvent instance.
     *
     * @var string
     */
    const STORE_ORDER = 'store.order';
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

namespace Acme\StoreBundle\Event;

use Symfony\Component\EventDispatcher\Event;
use Acme\StoreBundle\Order;

class FilterOrderEvent extends Event
{
    protected $order;

    public function __construct(Order $order)
    {
        $this->order = $order;
    }

    public function getOrder()
    {
        return $this->order;
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use Acme\StoreBundle\StoreEvents;
use Acme\StoreBundle\Order;
use Acme\StoreBundle\Event\FilterOrderEvent;

// the order is somehow created or retrieved
$order = new Order();
// ...

// create the FilterOrderEvent and dispatch it
$event = new FilterOrderEvent($order);
$dispatcher->dispatch(StoreEvents::STORE_ORDER, $event);

1
2
3
4
5
6
7
8

// some listener class that's been registered for "STORE_ORDER" event
use Acme\StoreBundle\Event\FilterOrderEvent;

public function onStoreOrder(FilterOrderEvent $event)
{
    $order = $event->getOrder();
    // do something to or with the order
}

Using Event Subscribers¶

The most common way to listen to an event is to register an event listener with the dispatcher. This listener can listen to one or more events and is notified each time those events are dispatched.

Another way to listen to events is via an event subscriber. An event subscriber is a PHP class that's able to tell the dispatcher exactly which events it should subscribe to. It implements the EventSubscriberInterface interface, which requires a single static method called getSubscribedEvents. Take the following example of a subscriber that subscribes to the kernel.response and store.order events:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

namespace Acme\StoreBundle\Event;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\FilterResponseEvent;

class StoreSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return array(
            'kernel.response' => array(
                array('onKernelResponsePre', 10),
                array('onKernelResponseMid', 5),
                array('onKernelResponsePost', 0),
            ),
            'store.order'     => array('onStoreOrder', 0),
        );
    }

    public function onKernelResponsePre(FilterResponseEvent $event)
    {
        // ...
    }

    public function onKernelResponseMid(FilterResponseEvent $event)
    {
        // ...
    }

    public function onKernelResponsePost(FilterResponseEvent $event)
    {
        // ...
    }

    public function onStoreOrder(FilterOrderEvent $event)
    {
        // ...
    }
}

This is very similar to a listener class, except that the class itself can tell the dispatcher which events it should listen to. To register a subscriber with the dispatcher, use the addSubscriber() method:

1
2
3
4

use Acme\StoreBundle\Event\StoreSubscriber;

$subscriber = new StoreSubscriber();
$dispatcher->addSubscriber($subscriber);

The dispatcher will automatically register the subscriber for each event returned by the getSubscribedEvents method. This method returns an array indexed by event names and whose values are either the method name to call or an array composed of the method name to call and a priority. The example above shows how to register several listener methods for the same event in subscriber and also shows how to pass the priority of each listener method. The higher the priority, the earlier the method is called. In the above example, when the kernel.response event is triggered, the methods onKernelResponsePre, onKernelResponseMid, and onKernelResponsePost are called in that order.

Stopping Event Flow/Propagation¶

In some cases, it may make sense for a listener to prevent any other listeners from being called. In other words, the listener needs to be able to tell the dispatcher to stop all propagation of the event to future listeners (i.e. to not notify any more listeners). This can be accomplished from inside a listener via the stopPropagation() method:

1
2
3
4
5
6
7
8

use Acme\StoreBundle\Event\FilterOrderEvent;

public function onStoreOrder(FilterOrderEvent $event)
{
    // ...

    $event->stopPropagation();
}

Now, any listeners to store.order that have not yet been called will not be called.

It is possible to detect if an event was stopped by using the isPropagationStopped() method which returns a boolean value:

1
2
3
4

$dispatcher->dispatch('foo.event', $event);
if ($event->isPropagationStopped()) {
    // ...
}

EventDispatcher aware Events and Listeners¶

New in version 2.1: The Event object contains a reference to the invoking dispatcher since Symfony 2.1

The EventDispatcher always injects a reference to itself in the passed event object. This means that all listeners have direct access to the EventDispatcher object that notified the listener via the passed Event object's getDispatcher() method.

This can lead to some advanced applications of the EventDispatcher including letting listeners dispatch other events, event chaining or even lazy loading of more listeners into the dispatcher object. Examples follow:

Lazy loading listeners:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

use Symfony\Component\EventDispatcher\Event;
use Acme\StoreBundle\Event\StoreSubscriber;

class Foo
{
    private $started = false;

    public function myLazyListener(Event $event)
    {
        if (false === $this->started) {
            $subscriber = new StoreSubscriber();
            $event->getDispatcher()->addSubscriber($subscriber);
        }

        $this->started = true;

        // ... more code
    }
}

Dispatching another event from within a listener:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use Symfony\Component\EventDispatcher\Event;

class Foo
{
    public function myFooListener(Event $event)
    {
        $event->getDispatcher()->dispatch('log', $event);

        // ... more code
    }
}

While this above is sufficient for most uses, if your application uses multiple EventDispatcher instances, you might need to specifically inject a known instance of the EventDispatcher into your listeners. This could be done using constructor or setter injection as follows:

Constructor injection:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use Symfony\Component\EventDispatcher\EventDispatcherInterface;

class Foo
{
    protected $dispatcher = null;

    public function __construct(EventDispatcherInterface $dispatcher)
    {
        $this->dispatcher = $dispatcher;
    }
}

Or setter injection:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use Symfony\Component\EventDispatcher\EventDispatcherInterface;

class Foo
{
    protected $dispatcher = null;

    public function setEventDispatcher(EventDispatcherInterface $dispatcher)
    {
        $this->dispatcher = $dispatcher;
    }
}

Choosing between the two is really a matter of taste. Many tend to prefer the constructor injection as the objects are fully initialized at construction time. But when you have a long list of dependencies, using setter injection can be the way to go, especially for optional dependencies.

Dispatcher Shortcuts¶

New in version 2.1: EventDispatcher::dispatch() method returns the event since Symfony 2.1.

The EventDispatcher::dispatch method always returns an Event object. This allows for various shortcuts. For example if one does not need a custom event object, one can simply rely on a plain Event object. You do not even need to pass this to the dispatcher as it will create one by default unless you specifically pass one:

1

$dispatcher->dispatch('foo.event');

Moreover, the EventDispatcher always returns whichever event object that was dispatched, i.e. either the event that was passed or the event that was created internally by the dispatcher. This allows for nice shortcuts:

1
2
3

if (!$dispatcher->dispatch('foo.event')->isPropagationStopped()) {
    // ...
}

Or:

1
2

$barEvent = new BarEvent();
$bar = $dispatcher->dispatch('bar.event', $barEvent)->getBar();

Or:

1

$response = $dispatcher->dispatch('bar.event', new BarEvent())->getBar();

and so on...

Event Name Introspection¶

New in version 2.1: Added event name to the Event object since Symfony 2.1

Since the EventDispatcher already knows the name of the event when dispatching it, the event name is also injected into the Event objects, making it available to event listeners via the getName() method.

The event name, (as with any other data in a custom event object) can be used as part of the listener's processing logic:

1
2
3
4
5
6
7
8
9

use Symfony\Component\EventDispatcher\Event;

class Foo
{
    public function myEventListener(Event $event)
    {
        echo $event->getName();
    }
}