[cookbook] add description of doctrine event subscriber #2301

Merged
merged 3 commits into from Mar 30, 2013

Projects

None yet

4 participants

@dbu
Contributor
dbu commented Mar 12, 2013

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 Member

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

dbu
dbu Mar 19, 2013 Contributor

done

@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 Member

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 Member

should be .. tip::

Contributor
dbu commented Mar 12, 2013

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

Contributor
dbu commented Mar 14, 2013

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

Member
wouterj commented Mar 14, 2013

@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 Member

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 Contributor

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 Member

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

Contributor
dbu commented Mar 19, 2013

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 Contributor

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

Contributor
dbu commented Mar 19, 2013

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
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