Restructured components to allow multiple parts and added more docs #1242

Closed
wants to merge 1 commit into
from
@@ -0,0 +1,87 @@
+.. index::
+ single: Event Dispatcher; Container Aware; Dependency Injection
+
+The Container Aware Event Dispatcher
+====================================
+
+Introduction
@stof
stof Apr 11, 2012 Member

you need a versionadded note saying it was moved to the component in 2.1 only

+------------
+
+The :class:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher` is
+a special event dispatcher implementation which is coupled to the Symfony2
+Dependency Injection Container Component (DIC). It allows DIC services to be
+specified as event listeners making the event dispatcher extremely powerful.
+
+Services are lazy loaded meaning the services attached as listeners will only be
+created if an event is dispatched that requires those listeners.
@stof
stof Apr 11, 2012 Member

you need to document somewhere that these services must be public ones

@ghost
ghost Apr 12, 2012

Good point, done.

+
+Setup
+-----
+
+Setup is straightforward by injecting a :class:`Symfony\Component\DependencyInjection\ContainerInterface`
+into the :class:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher`::
+
+ use Symfony\Component\DependencyInjection\ContainerBuilder;
+ use Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher;
+
+ $container = new Container();
@stof
stof Apr 11, 2012 Member

your use statement is about ContainerBuilder

@ghost
ghost Apr 12, 2012

Well stoffed :-)

+ $dispatcher = new ContainerAwareEventDispatcher($container);
+
+Adding Listeners
+----------------
+
+The ``Container Aware Event Dispatcher`` can either load directly specified
+services, or services as defined by :class:`Symfony\Component\EventDispatcher\EventSubscriberInterface`.
+
+The following examples assume the DIC has been loaded with the relevent services.
@jalliot
jalliot Apr 11, 2012 Contributor

typo: relevant

+
+Adding Services
+~~~~~~~~~~~~~~~
+
+Connecting existing service definitions is done with the
+:method:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher::addListenerService`
+method where the ``$callback`` is an array of ``array($serviceId, $methodName)``::
+
+ $dispatcher->addListenerService($eventName, array('foo', 'logListener'));
+
+Adding Subscriber Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``EventSubscribers`` can be added using the
+:method:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher::addSubscriberService`
+method as follows::
+
+ $dispatcher->addSubscriberService('kernel, 'StoreSubscriber');
@jalliot
jalliot Apr 11, 2012 Contributor

maybe precise that the second argument is the class name of the service

+
+The ``EventSubscriberInterface`` will be exactly as you would expect::
+
+ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+ class StoreSubscriber implements EventSubscriberInterface
+ {
+ static public function getSubscribedEvents()
+ {
+ return array(
+ 'kernel.response' => array(
+ array('onKernelResponsePre', 10),
+ array('onKernelResponsePost', 0),
+ ),
+ 'store.order' => array('onStoreOrder', 0),
+ );
+ }
+
+ public function onKernelResponsePre(FilterResponseEvent $event)
+ {
+ // ...
+ }
+
+ public function onKernelResponsePost(FilterResponseEvent $event)
+ {
+ // ...
+ }
+
+ public function onStoreOrder(FilterOrderEvent $event)
+ {
+ // ...
+ }
+ }
@@ -594,4 +594,4 @@ part of the listener's processing logic::
.. _Observer: http://en.wikipedia.org/wiki/Observer_pattern
.. _`Symfony2 HttpKernel component`: https://github.com/symfony/HttpKernel
.. _Closures: http://php.net/manual/en/functions.anonymous.php
-.. _PHP callable: http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback
+.. _PHP callable: http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback
@@ -0,0 +1,84 @@
+.. index::
+ single: Event Dispatcher
+
+The Generic Event Object
+========================
+
+.. versionadded:: 2.1
+ Added general purpose ``GenericEvent`` event class since Symfony 2.1
+
+The base ``Event`` class provided by the ``Event Dispatcher`` component is
+deliberately sparse to allow the creation of API specific event objects by
+inheritance using OOP. This allow for elegant and readable code in complex
+applications.
+
+However, for convenience, the ``Event Dispatcher`` component comes with a general
+purpose event class :class:`Symfony\Component\EventDispatcher\GenericEvent`
+for those who wish to use one event object throughout their application. Since
+it is suitable for most purposes out of the box, it avoids the need to
+create situation specific event objects suitable for less complex applications.
@jalliot
jalliot Apr 11, 2012 Contributor

less -> more no?

+
+``GenericEvent`` follows the standard observer pattern where the event object
+encapsulates an event 'subject', but has the addition of optional extra
+arguments and a convenient way of filtering data via an additional `data`
+property.
+
+The ``GenericEvent`` implements :phpclass:`ArrayAccess` on the event arguments
+which makes it very convenient to pass extra arguments regarding the event
+subject.
+
+The following examples show use-cases to give a general idea of the flexibility.
+The examples assume event listeners have been added to the dispatcher.
+
+Simply passing a subject::
+
+ use Symfony\Component\EventDispatcher\GenericEvent;
+
+ $event = GenericEvent($subject);
+ $dispatcher->dispatch('foo', $event);
+
+ class FooListener
+ {
+ public function handler(GenericEvent $event)
+ {
+ if ($event->getSubject() instanceof Foo) {
+ // ...
+ }
+ }
+ }
+
+Passing and processing arguments::
+
+ use Symfony\Component\EventDispatcher\GenericEvent;
+
+ $event = GenericEvent($subject, array('type' => 'foo', 'counter' => 0)));
+ $dispatcher->dispatch('foo', $event);
+
+ echo $event['counter'];
+
+ class FooListener
+ {
+ public function handler(GenericEvent $event)
+ {
+ if (isset($event['type']) && $event['type'] == 'foo') {
@stof
stof Apr 11, 2012 Member

=== would be better :)

+ // ... do something
+ }
+
+ $event['counter']++;
+ }
+ }
+
+Filtering data::
+
+ $event = GenericEvent($subject, array(), $data);
+ $dispatcher->dispatch('foo', $event);
+
+ echo $event->getData();
+
+ class FooListener
+ {
+ public function filter(GenericEvent $event)
+ {
+ $event->setData(strtolower($event->getData()));
+ }
+ }
Oops, something went wrong.