[cookbook] add description of doctrine event subscriber #2301

Merged
merged 3 commits into from Mar 30, 2013

Projects

None yet

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 Mar 12, 2013
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
wouterj Mar 12, 2013

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

@wouterj wouterj commented on an outdated diff Mar 12, 2013
cookbook/doctrine/event_listeners_subscribers.rst
+ 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
wouterj Mar 12, 2013

please add new lines before each method name

@wouterj wouterj commented on an outdated diff Mar 12, 2013
cookbook/doctrine/event_listeners_subscribers.rst
+ {
+ $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
wouterj Mar 12, 2013

should be .. tip::

@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
Symfony member

@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 Mar 15, 2013
cookbook/doctrine/event_listeners_subscribers.rst
+ $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 Mar 15, 2013

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 Mar 18, 2013

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 Mar 18, 2013

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

@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 Mar 19, 2013
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 Mar 19, 2013

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

@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 Mar 30, 2013
@weaverryan
Symfony member

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