Merge pull request #2301 from dbu/explain-doctrine-event-subscribers

weaverryan · weaverryan · commit 508e2e6d23da · 2013-03-30T10:35:26.000-07:00
[cookbook] add description of doctrine event subscriber
diff --git a/components/event_dispatcher/introduction.rst b/components/event_dispatcher/introduction.rst
@@ -380,6 +380,8 @@ can be the way to go, especially for optional dependencies.
 .. index::
    single: Event Dispatcher; Event subscribers
 
+.. _event_dispatcher-using-event-subscribers:
+
 Using Event Subscribers
 ~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/cookbook/doctrine/event_listeners_subscribers.rst b/cookbook/doctrine/event_listeners_subscribers.rst
@@ -17,6 +17,8 @@ Doctrine defines two types of objects that can listen to Doctrine events:
 listeners and subscribers. Both are very similar, but listeners are a bit
 more straightforward. For more, see `The Event System`_ on Doctrine's website.
 
+The Doctrine website also explains all existing events that can be listened to.
+
 Configuring the Listener/Subscriber
 -----------------------------------
 
@@ -120,7 +122,9 @@ Creating the Listener Class
 
 In the previous example, a service ``my.listener`` was configured as a Doctrine
 listener on the event ``postPersist``. That class behind that service must have
-a ``postPersist`` method, which will be called when the event is thrown::
+a ``postPersist`` method, which will be called when the event is thrown.
+
+.. code-block::php
 
     // src/Acme/SearchBundle/EventListener/SearchIndexer.php
     namespace Acme\SearchBundle\EventListener;
@@ -152,4 +156,62 @@ specific type of entity (e.g. a ``Product`` entity but not a ``BlogPost``
 entity), you should check for the class name of the entity in your method
 (as shown above).
 
-.. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/2.1/reference/events.html
+Creating the Subscriber Class
+-----------------------------
+
+A doctrine event subscriber must implement the ``Doctrine\Common\EventSubscriber``
+interface and an event method for each event it subscribes to.
+
+.. code-block::php
+
+    // src/Acme/SearchBundle/EventListener/SearchIndexerSubscriber.php
+    namespace Acme\SearchBundle\EventListener;
+
+    use Doctrine\Common\EventSubscriber;
+    use Doctrine\ORM\Event\LifecycleEventArgs;
+    // for doctrine 2.4: Doctrine\Common\Persistence\Event\LifecycleEventArgs;
+    use Acme\StoreBundle\Entity\Product;
+
+    class SearchIndexerSubscriber implements EventSubscriber
+    {
+        public function getSubscribedEvents()
+        {
+            return array(
+                'postPersist',
+                'postUpdate',
+            );
+        }
+
+        public function postUpdate(LifecycleEventArgs $args)
+        {
+            $this->index($args);
+        }
+
+        public function postPersist(LifecycleEventArgs $args)
+        {
+            $this->index($args);
+        }
+
+        public function index(LifecycleEventArgs $args)
+        {
+            $entity = $args->getEntity();
+            $entityManager = $args->getEntityManager();
+
+            // perhaps you only want to act on some "Product" entity
+            if ($entity instanceof Product) {
+                // ... do something with the Product
+            }
+        }
+    }
+
+.. tip::
+
+    Doctrine event subscribers can not return a flexible array of methods to
+    call for the events like the :ref:`Symfony event subscriber <event_dispatcher-using-event-subscribers>`
+    can do. Doctrine event subscribers must return a simple array of the event
+    names they subscribe to. Doctrine will then expect methods on the subscriber
+    with the names of the subscribed events, just as when using an event listener.
+
+For a full reference, see chapter `The Event System` in the doctrine documentation.
+
+.. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
