Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

[cookbook] add description of doctrine event subscriber #2301

Merged
merged 3 commits into from

4 participants

@dbu

this confused me quite a bit, so i thought i better document it: the doctrine event subscriber is simpler than the symfony event subscriber. if you return from doctrine an array mapping event names to method names, doctrine will register for "events" with the names of those methods.

@WouterJ WouterJ commented on the diff
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.
+
+
@WouterJ Collaborator
WouterJ added a note

You should add .. code-block::php before this line

@dbu
dbu added a note

done

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/doctrine/event_listeners_subscribers.rst
((12 lines not shown))
+ 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)
@WouterJ Collaborator
WouterJ added a note

please add new lines before each method name

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/doctrine/event_listeners_subscribers.rst
((32 lines not shown))
+ {
+ $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::
@WouterJ Collaborator
WouterJ added a note

should be .. tip::

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dbu

sorry, seem to be tired. fixed those (and the source of my copy-paste too)

@dbu

@WouterJ i fixed the styling problems. ok to merge?

@WouterJ
Collaborator

@dbu yes, I think so. But @weaverryan is the only person who can merge, so you need to wait until he has some time to merge some PRs.

@stof stof commented on the diff
cookbook/doctrine/event_listeners_subscribers.rst
((42 lines not shown))
+ $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.
@stof
stof added a note

I think you should contribute this to the Doctrine Common documentation about the EventManager instead and link it from the Symfony doc. Let's improve the doc of the Doctrine project as well :)

@dbu
dbu added a note

i can try an update of the event listener doc in doctrine as well. but i still think that at least this tip belongs here rather than into the doctrine doc.
the doctrine doc already has an example of event listeners, but not event subscribers i think. i thought it does make sense to have the minimal examples here in the symfony doc too, to see how it works and then follow the link for details. how much of this cookbook entry would you want to remove?

@stof
stof added a note

well, the doctrine doc should have an example of subscribers IMO

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dbu

i did a pull request on doctrine doc now doctrine/orm-documentation#155 and added more links from here to that doc. i think it is useful to have the concrete examples right here in this cookbook entry, even if its duplication.

@dbu dbu commented on the diff
cookbook/doctrine/event_listeners_subscribers.rst
@@ -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
@dbu
dbu added a note

this link lead to a 404. i changed it (but git diff puts it at the very bottom of what i added here...)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dbu

created a doctrine PR on the right repository now: doctrine/doctrine2#621

any other feedback on this?

@weaverryan weaverryan merged commit 508e2e6 into symfony:2.0
@weaverryan
Collaborator

Hey David!

Very nice addition! I've merged this in with only minor tweaks at sha: 6f191da.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 12, 2013
  1. @dbu

    add description of doctrine event subscriber and hint on difference b…

    dbu authored
    …etween symfony and doctrine event subscriber
  2. @dbu

    layout fixes

    dbu authored
Commits on Mar 19, 2013
  1. @dbu
This page is out of date. Refresh to see the latest.
View
2  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
~~~~~~~~~~~~~~~~~~~~~~~
View
66 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
@dbu
dbu added a note

this link lead to a 404. i changed it (but git diff puts it at the very bottom of what i added here...)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+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
@WouterJ Collaborator
WouterJ added a note

You should add .. code-block::php before this line

@dbu
dbu added a note

done

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+ // 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.
@stof
stof added a note

I think you should contribute this to the Doctrine Common documentation about the EventManager instead and link it from the Symfony doc. Let's improve the doc of the Doctrine project as well :)

@dbu
dbu added a note

i can try an update of the event listener doc in doctrine as well. but i still think that at least this tip belongs here rather than into the doctrine doc.
the doctrine doc already has an example of event listeners, but not event subscribers i think. i thought it does make sense to have the minimal examples here in the symfony doc too, to see how it works and then follow the link for details. how much of this cookbook entry would you want to remove?

@stof
stof added a note

well, the doctrine doc should have an example of subscribers IMO

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+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
Something went wrong with that request. Please try again.