diff --git a/components/event_dispatcher/introduction.rst b/components/event_dispatcher/introduction.rst index 8279d679c0b..33f5f16b712 100644 --- a/components/event_dispatcher/introduction.rst +++ b/components/event_dispatcher/introduction.rst @@ -29,7 +29,7 @@ The Symfony EventDispatcher component implements the `Mediator`_ pattern in a simple and effective way to make all these things possible and to make your projects truly extensible. -Take a simple example from :doc:`/components/http_kernel/introduction`. +Take a simple example from :doc:`the HttpKernel component `. Once a ``Response`` object has been created, it may be useful to allow other elements in the system to modify it (e.g. add some cache headers) before it's actually used. To make this possible, the Symfony kernel throws an @@ -81,17 +81,10 @@ Naming Conventions The unique event name can be any string, but optionally follows a few simple naming conventions: -* use only lowercase letters, numbers, dots (``.``) and underscores (``_``); - -* prefix names with a namespace followed by a dot (e.g. ``kernel.``); - -* end names with a verb that indicates what action is being taken (e.g. - ``request``). - -Here are some examples of good event names: - -* ``kernel.response`` -* ``form.pre_set_data`` +* Use only lowercase letters, numbers, dots (``.``) and underscores (``_``); +* Prefix names with a namespace followed by a dot (e.g. ``order.``, ``user.*``); +* End names with a verb that indicates what action has been taken (e.g. + ``order.placed``). .. index:: single: EventDispatcher; Event subclasses @@ -105,19 +98,18 @@ contains a method for stopping :ref:`event propagation `, but not much else. +.. seealso:: + + Read ":doc:`/components/event_dispatcher/generic_event`" for more + information about this base event object. + Often times, data about a specific event needs to be passed along with the -``Event`` object so that the listeners have needed information. In the case -of the ``kernel.response`` event, the ``Event`` object that's created and -passed to each listener is actually of type -:class:`Symfony\\Component\\HttpKernel\\Event\\FilterResponseEvent`, a -subclass of the base ``Event`` object. This class contains methods such -as ``getResponse`` and ``setResponse``, allowing listeners to get or even -replace the ``Response`` object. - -The moral of the story is this: When creating a listener to an event, the -``Event`` object that's passed to the listener may be a special subclass -that has additional methods for retrieving information from and responding -to the event. +``Event`` object so that the listeners have the needed information. In such +case, a special subclass that has additional methods for retrieving and +overriding information can be passed when dispatching an event. For example, +the ``kernel.response`` event uses a +:class:`Symfony\\Component\\HttpKernel\\Event\\FilterResponseEvent`, which +contains methods to get and even replace the ``Response`` object. The Dispatcher ~~~~~~~~~~~~~~ @@ -143,20 +135,17 @@ A call to the dispatcher's ``addListener()`` method associates any valid PHP callable to an event:: $listener = new AcmeListener(); - $dispatcher->addListener('foo.action', array($listener, 'onFooAction')); + $dispatcher->addListener('acme.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 and therefore - that the listener will be triggered earlier) 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. +#. The event name (string) that this listener wants to listen to; +#. A PHP callable that will be executed when the specified event is dispatched; +#. An optional priority integer (higher equals more important and therefore + that the listener will be triggered earlier) 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. .. note:: @@ -164,7 +153,7 @@ The ``addListener()`` method takes up to three arguments: ``call_user_func()`` function and returns ``true`` when passed to the ``is_callable()`` function. It can be a ``\Closure`` instance, an object implementing an ``__invoke`` method (which is what closures are in fact), - a string representing a function, or an array representing an object + a string representing a function or an array representing an object method or a class method. So far, you've seen how PHP objects can be registered as listeners. @@ -178,7 +167,7 @@ The ``addListener()`` method takes up to three arguments: 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 dispatcher calls the ``AcmeListener::onFooAction()`` method and passes the ``Event`` object as the single argument:: use Symfony\Component\EventDispatcher\Event; @@ -193,23 +182,10 @@ the ``Event`` object as the single argument:: } } -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.response`` event -passes an instance of -``Symfony\Component\HttpKernel\Event\FilterResponseEvent``:: - - use Symfony\Component\HttpKernel\Event\FilterResponseEvent; - - public function onKernelResponse(FilterResponseEvent $event) - { - $response = $event->getResponse(); - $request = $event->getRequest(); - - // ... - } +The ``$event`` argument is the event class that was passed when dispatching the +event. In many cases, a special event subclass is passed with extra +information. You can check the documentation or implementation of each event to +determine which instance is passed. .. sidebar:: Registering Event Listeners in the Service Container @@ -268,57 +244,29 @@ 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. -The Static ``Events`` Class -........................... - -Suppose you want to create a new Event - ``store.order`` - that is dispatched -each time an order is created inside your application. To keep things -organized, start by creating a ``StoreEvents`` class inside your application -that serves to define and document your event:: - - 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'; - } - -Notice that this class doesn't actually *do* anything. The purpose of the -``StoreEvents`` class is just to be a location where information about common -events can be centralized. Notice also that a special ``FilterOrderEvent`` -class will be passed to each listener of this event. +.. _creating-an-event-object: -Creating an Event Object -........................ +Creating an Event Class +....................... -Later, when you dispatch this new event, you'll create an ``Event`` instance -and pass it to the dispatcher. The dispatcher then passes this same instance -to each of the listeners of the event. If you don't need to pass any -information to your listeners, you can use the default -``Symfony\Component\EventDispatcher\Event`` class. Most of the time, however, -you *will* need to pass information about the event to each listener. To -accomplish this, you'll create a new class that extends -``Symfony\Component\EventDispatcher\Event``. +Suppose you want to create a new event - ``order.placed`` - that is dispatched +each time a customer orders a product with your application. When dispatching +this event, you'll pass a custom event instance that has access to the placed +order. Start by creating this custom event class and documenting it:: -In this example, each listener will need access to some pretend ``Order`` -object. Create an ``Event`` class that makes this possible:: - - namespace Acme\StoreBundle\Event; + namespace Acme\Store\Event; use Symfony\Component\EventDispatcher\Event; - use Acme\StoreBundle\Order; + use Acme\Store\Order; - class FilterOrderEvent extends Event + /** + * The order.placed event is dispatched each time an order is created + * in the system. + */ + class OrderPlacedEvent extends Event { + const NAME = 'order.placed'; + protected $order; public function __construct(Order $order) @@ -332,8 +280,16 @@ object. Create an ``Event`` class that makes this possible:: } } -Each listener now has access to the ``Order`` object via the ``getOrder`` -method. +Each listener now has access to the order via the ``getOrder()`` method. + +.. note:: + + If you don't need to pass any additional data to the event listeners, you + can also use the default + :class:`Symfony\\Component\\EventDispatcher\\Event` class. In such case, + you can document the event and its name in a generic ``StoreEvents`` class, + similar to the :class:`Symfony\\Component\\HttpKernel\\KernelEvents` + class. Dispatch the Event .................. @@ -343,31 +299,20 @@ method notifies all listeners of the given event. It takes two arguments: the name of the event to dispatch and the ``Event`` instance to pass to each listener of that event:: - use Acme\StoreBundle\StoreEvents; - use Acme\StoreBundle\Order; - use Acme\StoreBundle\Event\FilterOrderEvent; + use Acme\Store\Order; + use Acme\Store\Event\OrderPlacedEvent; // 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); - -Notice that the special ``FilterOrderEvent`` object is created and passed -to the ``dispatch`` method. Now, any listener to the ``store.order`` event -will receive the ``FilterOrderEvent`` and have access to the ``Order`` object -via the ``getOrder`` method:: - - // some listener class that's been registered for "store.order" event - use Acme\StoreBundle\Event\FilterOrderEvent; + // create the OrderPlacedEvent and dispatch it + $event = new OrderPlacedEvent($order); + $dispatcher->dispatch(OrderPlacedEvent::NAME, $event); - public function onStoreOrder(FilterOrderEvent $event) - { - $order = $event->getOrder(); - // do something to or with the order - } +Notice that the special ``OrderPlacedEvent`` object is created and passed to +the ``dispatch()`` method. Now, any listener to the ``order.placed`` +event will receive the ``OrderPlacedEvent``. .. index:: single: EventDispatcher; Event subscribers @@ -386,26 +331,27 @@ subscriber is a PHP class that's able to tell the dispatcher exactly which events it should subscribe to. It implements the :class:`Symfony\\Component\\EventDispatcher\\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:: +:method:`Symfony\\Component\\EventDispatcher\\EventSubscriberInterface::getSubscribedEvents`. +Take the following example of a subscriber that subscribes to the +``kernel.response`` and ``order.placed`` events:: - namespace Acme\StoreBundle\Event; + namespace Acme\Store\Event; use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Component\HttpKernel\Event\FilterResponseEvent; - use Acme\StoreBundle\Event\FilterOrderEvent; + use Symfony\Component\HttpKernel\KernelEvents; + use Acme\Store\Event\OrderPlacedEvent; class StoreSubscriber implements EventSubscriberInterface { public static function getSubscribedEvents() { return array( - 'kernel.response' => array( + KernelEvents::RESPONSE => array( array('onKernelResponsePre', 10), - array('onKernelResponseMid', 5), - array('onKernelResponsePost', 0), + array('onKernelResponsePost', -10), ), - 'store.order' => array('onStoreOrder', 0), + OrderPlacedEvent::NAME => 'onStoreOrder', ); } @@ -414,17 +360,12 @@ subscribes to the ``kernel.response`` and ``store.order`` events:: // ... } - public function onKernelResponseMid(FilterResponseEvent $event) - { - // ... - } - public function onKernelResponsePost(FilterResponseEvent $event) { // ... } - public function onStoreOrder(FilterOrderEvent $event) + public function onStoreOrder(OrderPlacedEvent $event) { // ... } @@ -436,21 +377,22 @@ with the dispatcher, use the :method:`Symfony\\Component\\EventDispatcher\\EventDispatcher::addSubscriber` method:: - use Acme\StoreBundle\Event\StoreSubscriber; + use Acme\Store\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 +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. +``onKernelResponsePre()`` and ``onKernelResponsePost()`` are called in that +order. .. index:: single: EventDispatcher; Stopping event flow @@ -467,22 +409,23 @@ the dispatcher to stop all propagation of the event to future listeners inside a listener via the :method:`Symfony\\Component\\EventDispatcher\\Event::stopPropagation` method:: - use Acme\StoreBundle\Event\FilterOrderEvent; + use Acme\Store\Event\OrderPlacedEvent; - public function onStoreOrder(FilterOrderEvent $event) + public function onStoreOrder(OrderPlacedEvent $event) { // ... $event->stopPropagation(); } -Now, any listeners to ``store.order`` that have not yet been called will +Now, any listeners to ``order.placed`` that have not yet been called will *not* be called. It is possible to detect if an event was stopped by using the :method:`Symfony\\Component\\EventDispatcher\\Event::isPropagationStopped` method which returns a boolean value:: + // ... $dispatcher->dispatch('foo.event', $event); if ($event->isPropagationStopped()) { // ... @@ -502,83 +445,9 @@ event object. This means that all listeners have direct access to the object's :method:`Symfony\\Component\\EventDispatcher\\Event::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:: - - 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:: - - 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:: - - use Symfony\Component\EventDispatcher\EventDispatcherInterface; - - class Foo - { - protected $dispatcher = null; - - public function __construct(EventDispatcherInterface $dispatcher) - { - $this->dispatcher = $dispatcher; - } - } - -Or setter injection:: - - 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. +This can lead to some advanced applications of the ``EventDispatcher`` +including dispatching other events inside listeners, chaining events or even +lazy loading listeners into the dispatcher object. .. index:: single: EventDispatcher; Dispatcher shortcuts @@ -588,15 +457,12 @@ can be the way to go, especially for optional dependencies. Dispatcher Shortcuts ~~~~~~~~~~~~~~~~~~~~ -The :method:`EventDispatcher::dispatch ` -method always returns an :class:`Symfony\\Component\\EventDispatcher\\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 +If you do not need a custom event object, you can simply rely on a plain :class:`Symfony\\Component\\EventDispatcher\\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:: +need to pass this to the dispatcher as it will create one by default unless you +specifically pass one:: - $dispatcher->dispatch('foo.event'); + $dispatcher->dispatch('order.placed'); Moreover, the event dispatcher always returns whichever event object that was dispatched, i.e. either the event that was passed or the event that @@ -608,14 +474,10 @@ was created internally by the dispatcher. This allows for nice shortcuts:: Or:: - $barEvent = new BarEvent(); - $bar = $dispatcher->dispatch('bar.event', $barEvent)->getBar(); - -Or:: - - $bar = $dispatcher->dispatch('bar.event', new BarEvent())->getBar(); + $event = new OrderPlacedEvent($order); + $order = $dispatcher->dispatch('bar.event', $event)->getOrder(); -and so on... +and so on. .. index:: single: EventDispatcher; Event name introspection @@ -648,10 +510,12 @@ Other Dispatchers ----------------- Besides the commonly used ``EventDispatcher``, the component comes -with 2 other dispatchers: +with some other dispatchers: * :doc:`/components/event_dispatcher/container_aware_dispatcher` * :doc:`/components/event_dispatcher/immutable_dispatcher` +* :doc:`/components/event_dispatcher/traceable_dispatcher` (provided by the + :doc:`HttpKernel component `) .. _Mediator: https://en.wikipedia.org/wiki/Mediator_pattern .. _Closures: http://php.net/manual/en/functions.anonymous.php