Merge pull request #839 from ThomasLandauer/patch-1

Complete example

Resources/doc/entity-listeners.rst

@@ -1,21 +1,57 @@
 Entity Listeners
 ================
 
-Entity listeners that are services must be registered with the entity
-listener resolver. You can tag your entity listeners and they will automatically
-be added to the resolver. Use the entity_manager attribute to specify which
-entity manager it should be registered with. Example:
+To set up an entity listener, start by creating a listener class:
+
+.. code-block:: php
+
+    // src/EventListener/UserListener
+    namespace App\EventListener;
+
+    use Doctrine\ORM\Event\LifecycleEventArgs;
+    use App\Entity\User;
+
+    class UserListener
+    {    
+        public function prePersist(User $user, LifecycleEventArgs $event)
+        {
+            // ...
+        }
+    }
+
+Next, you have to register the class as a listener. There are two ways to
+achieve this:
+
+You can either do the registration in your entity like this:
+
+.. code-block:: php
+
+    // src/Entity/User.php
+    namespace App\Entity\User;
+
+    use Doctrine\ORM\Mapping as ORM;
+
+    /**
+     * @ORM\Entity
+     * @ORM\EntityListeners({"App\EventListener\UserListener"})
+     */
+    class User
+    {
+        // ...
+    }
+
+This works fine, but your event listener will not be registered as a service
+(even if you have ``autowire: true`` in your ``services.yaml``). So to register
+it as a service, you have to add this to your ``services.yaml``:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         services:
-            user_listener:
-                class: \UserListener
+            App\EventListener\UserListener:
                 tags:
                     - { name: doctrine.orm.entity_listener }
-                    - { name: doctrine.orm.entity_listener, entity_manager: custom }
 
     .. code-block:: xml
 
@@ -25,30 +61,23 @@ entity manager it should be registered with. Example:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 
             <services>
-                <service id="user_listener" class="UserListener">
+                <service id="App\EventListener\UserListener">
                     <tag name="doctrine.orm.entity_listener" />
-                    <tag name="doctrine.orm.entity_listener" entity_manager="custom" />
                 </service>
             </services>
         </container>
 
-If you use a version of doctrine/orm < 2.5 you have to register the entity listener in your entity as well:
+Alternatively, you could do the entire configuration in ``services.yaml`` and
+omit the ``@ORM\EntityListeners`` annotation in the entity:
 
-.. code-block:: php
+.. code-block:: yaml
 
-    <?php
-    // User.php
+    services:
+        App\EventListener\UserListener:
+            tags:
+                - { name: doctrine.orm.entity_listener, entity: App\Entity\User, event: prePersist }
 
-    use Doctrine\ORM\Mapping as ORM;
-
-    /**
-     * @ORM\Entity
-     * @ORM\EntityListeners({"UserListener"})
-     */
-    class User
-    {
-        // ....
-    }
+To register the listener for a custom entity manager, just add the ``entity_manager`` attribute.
 
-See also http://doctrine-orm.readthedocs.org/en/latest/reference/events.html#entity-listeners for more info on entity listeners.
+See also https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/events.html#entity-listeners for more info on entity listeners.