From 26077b550f280ac1122d1bc7463f6a26da1856a6 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Tue, 12 Mar 2013 17:50:18 +0100 Subject: [PATCH 1/3] add description of doctrine event subscriber and hint on difference between symfony and doctrine event subscriber --- components/event_dispatcher/introduction.rst | 2 + .../doctrine/event_listeners_subscribers.rst | 52 +++++++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/components/event_dispatcher/introduction.rst b/components/event_dispatcher/introduction.rst index 915317bf254..bf028503382 100644 --- 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 index 1f1d54a3ce8..b959c0211ee 100644 --- a/cookbook/doctrine/event_listeners_subscribers.rst +++ b/cookbook/doctrine/event_listeners_subscribers.rst @@ -152,4 +152,56 @@ 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). +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. + + + // src/Acme/SearchBundle/EventListener/SearchIndexerSubscriber.php + namespace Acme\SearchBundle\EventListener; + + use Doctrine\Common\EventSubscriber; + use Doctrine\ORM\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 + } + } + } + +.. hint:: + + Doctrine event subscribers can not return a flexible array of methods to + call for the events like the :ref:`Symfony event subscriber ` + 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. + + .. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/2.1/reference/events.html From 357ad55f4070c32d1a58a941331708c0e8b6f31e Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Tue, 12 Mar 2013 19:35:41 +0100 Subject: [PATCH 2/3] layout fixes --- cookbook/doctrine/event_listeners_subscribers.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/cookbook/doctrine/event_listeners_subscribers.rst b/cookbook/doctrine/event_listeners_subscribers.rst index b959c0211ee..983b1503aa3 100644 --- a/cookbook/doctrine/event_listeners_subscribers.rst +++ b/cookbook/doctrine/event_listeners_subscribers.rst @@ -120,7 +120,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; @@ -158,6 +160,7 @@ 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; @@ -175,14 +178,17 @@ interface and an event method for each event it subscribes to. '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(); @@ -195,7 +201,7 @@ interface and an event method for each event it subscribes to. } } -.. hint:: +.. tip:: Doctrine event subscribers can not return a flexible array of methods to call for the events like the :ref:`Symfony event subscriber ` From 0924f5ce7446b2dc1c85071b357dc655eab8fbe5 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Tue, 19 Mar 2013 09:11:32 +0100 Subject: [PATCH 3/3] more reference to the doctrine documentation --- cookbook/doctrine/event_listeners_subscribers.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/cookbook/doctrine/event_listeners_subscribers.rst b/cookbook/doctrine/event_listeners_subscribers.rst index 983b1503aa3..6c2ddb2734a 100644 --- 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 ----------------------------------- @@ -167,6 +169,7 @@ interface and an event method for each event it subscribes to. 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 @@ -209,5 +212,6 @@ interface and an event method for each event it subscribes to. 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/2.1/reference/events.html +.. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html