adding some more doc and examples for lifecycle event listeners and subscribers

docs/en/reference/events.rst

@@ -2,7 +2,9 @@ Events
 ======
 
 Doctrine 2 features a lightweight event system that is part of the
-Common package.
+Common package. Doctrine uses it to dispatch system events, mainly
+:ref:`lifecycle events <reference-events-lifecycle-events>`.
+You can also use it for your own custom events.
 
 The Event System
 ----------------
@@ -95,7 +97,15 @@ array of events it should be subscribed to.
     $eventSubscriber = new TestEventSubscriber();
     $evm->addEventSubscriber($eventSubscriber);
 
-Now when you dispatch an event any event subscribers will be
+.. note::
+
+    If you are familiar with the Symfony2 event manager, note that
+    the array returned by getSubscribedEvents is different. For
+    doctrine, the array values must be the event names, and the
+    names are used as method names that will be called when the
+    event occurs.
+
+Now when you dispatch an event, any event subscribers will be
 notified for that event.
 
 .. code-block:: php
@@ -133,6 +143,8 @@ several reasons:
 An example for a correct notation can be found in the example
 ``EventTest`` above.
 
+.. _reference-events-lifecycle-events:
+
 Lifecycle Events
 ----------------
 
@@ -198,7 +210,7 @@ listeners:
 
 -  Lifecycle Callbacks are methods on the entity classes that are
    called when the event is triggered. They receives some kind of ``EventArgs``.
--  Lifecycle Event Listeners are classes with specific callback
+-  Lifecycle Event Listeners and Subscribers are classes with specific callback
    methods that receives some kind of ``EventArgs`` instance which
    give access to the entity, EntityManager or other relevant data.
 
@@ -360,8 +372,8 @@ With the additional argument you have access to the
         }
     }
 
-Listening to Lifecycle Events
------------------------------
+Listening and subscribing to Lifecycle Events
+---------------------------------------------
 
 Lifecycle event listeners are much more powerful than the simple
 lifecycle callbacks that are defined on the entity classes. They
@@ -371,7 +383,66 @@ workings of the EntityManager and UnitOfWork. Please read the
 *Implementing Event Listeners* section carefully if you are trying
 to write your own listener.
 
-To register an event listener you have to hook it into the
+For event subscribers, there are no surprises. They declare the
+lifecycle events in their ``getSubscribedEvents`` method and provide
+public methods that expect the relevant arguments.
+
+A lifecycle event listener looks like the following:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
+
+    class MyEventListener
+    {
+        public function preUpdate(LifecycleEventArgs $args)
+        {
+            $entity = $args->getObject();
+            $entityManager = $args->getObjectManager();
+
+            // perhaps you only want to act on some "Product" entity
+            if ($entity instanceof Product) {
+                // do something with the Product
+            }
+        }
+    }
+
+A lifecycle event subscriber may looks like this:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\Common\EventSubscriber;
+    use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
+
+    class MyEventSubscriber implements EventSubscriber
+    {
+        public function getSubscribedEvents()
+        {
+            return array(
+                'postUpdate',
+            );
+        }
+
+        public function postUpdate(LifecycleEventArgs $args)
+        {
+            $entity = $args->getObject();
+            $entityManager = $args->getObjectManager();
+
+            // perhaps you only want to act on some "Product" entity
+            if ($entity instanceof Product) {
+                // do something with the Product
+            }
+        }
+
+.. note::
+
+    Lifecycle events are triggered for all entities. It is the responsibility
+    of the listeners and subscribers to check if the entity is of a type
+    it wants to handle.
+
+To register an event listener or subscriber, you have to hook it into the
 EventManager that is passed to the EntityManager factory:
 
 .. code-block:: php