From 5149dfd5c67a02a6cc3ca9f77e5d914232649cce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Tue, 19 Dec 2023 20:43:30 +0100 Subject: [PATCH] Update documentation for AsDocumentListener --- EventSubscriber/EventSubscriberInterface.php | 2 +- Resources/doc/events.rst | 169 +++++-------------- UPGRADE-5.0.md | 2 + 3 files changed, 44 insertions(+), 129 deletions(-) diff --git a/EventSubscriber/EventSubscriberInterface.php b/EventSubscriber/EventSubscriberInterface.php index ec4e4025..1768b16d 100644 --- a/EventSubscriber/EventSubscriberInterface.php +++ b/EventSubscriber/EventSubscriberInterface.php @@ -6,7 +6,7 @@ use Doctrine\Common\EventSubscriber; -/** @deprecated use the {@see \Doctrine\Bundle\MongoDBBundle\Attribute\AsDocumentListener} attribute instead */ +/** @deprecated since 4.7.0, use the {@see \Doctrine\Bundle\MongoDBBundle\Attribute\AsDocumentListener} attribute instead */ interface EventSubscriberInterface extends EventSubscriber { } diff --git a/Resources/doc/events.rst b/Resources/doc/events.rst index 12b676cd..492cc7bc 100644 --- a/Resources/doc/events.rst +++ b/Resources/doc/events.rst @@ -11,155 +11,71 @@ see Doctrine's `Event Documentation`_. document managers tied to that connection. Listeners and subscribers may be registered with all event managers or just one (using the connection name). -In Symfony, you can register a listener or subscriber by creating a service -and then `tagging`_ it with a specific tag. +To register a service to act as an event listener you have to tag it with the +``doctrine_mongodb.odm.event_listener`` tag. -Event Listeners ---------------- - -Use the ``doctrine_mongodb.odm.event_listener`` tag to -register a listener. The ``event`` attribute is required and should denote -the event on which to listen. By default, listeners will be registered with -event managers for all connections. To restrict a listener to a single -connection, specify its name in the tag's ``connection`` attribute. - -The ``priority`` attribute, which defaults to ``0`` if omitted, may be used -to control the order in which listeners are registered. Much like Symfony's -`event dispatcher`_, greater number will result in the listener executing -first and listeners with the same priority will be executed in the order that -they were registered with the event manager. - -Lastly, the ``lazy`` attribute, which defaults to ``false`` if omitted, may -be used to request that the listener be lazily loaded by the event manager -when its event is dispatched. +Starting with Doctrine bundle 2.8, you can use the ``AsDocumentListener`` attribute to tag the service. .. configuration-block:: - .. code-block:: yaml - - services: - my_doctrine_listener: - class: App\Listener\MyDoctrineListener - # ... - tags: - - { name: doctrine_mongodb.odm.event_listener, event: postPersist } - - .. code-block:: xml - - - - - - - .. code-block:: php + .. code-block:: php-attributes - $definition = new Definition('App\Listener\MyDoctrineListener'); - // ... - $definition->addTag('doctrine_mongodb.odm.event_listener', [ - 'event' => 'postPersist', - ]); - $container->setDefinition('my_doctrine_listener', $definition); + // src/App/EventListener/SearchIndexer.php + namespace App\EventListener; -Event Subscribers ------------------ + use Doctrine\Bundle\MongoDBBundle\Attribute\AsDocumentListener; + use Doctrine\ORM\Event\LifecycleEventArgs; -Implement ``Doctrine\Bundle\MongoDBBundle\EventSubscriber\EventSubscriberInterface`` -and `autoconfiguration`_ to automatically register your class as a MongoODM -event subscriber. - -.. code-block:: php - - // src/App/EventSubscriber/MongoDB/ProductSubscriber.php - namespace App\EventSubscriber\MongoDB; - - use App\Document\Product; - use Doctrine\Bundle\MongoDBBundle\EventSubscriber\EventSubscriberInterface; - - class ProductSubscriber implements EventSubscriberInterface - { - public function getSubscribedEvents() + #[AsDocumentListener('postPersist', priority: 500, connection: 'default')] + class SearchIndexer { - return [ - // List events to subscribe - ]; + public function postPersist(LifecycleEventArgs $event): void + { + // ... + } } - } - -.. configuration-block:: .. code-block:: yaml # config/services.yaml services: + # ... - App\EventSubscriber\MongoDB\: - resource: '../src/EventSubscriber/MongoDB/*' - autoconfigure: true - - .. code-block:: xml - - - - - - - - - - -Alternatively, use the ``doctrine_mongodb.odm.event_subscriber`` tag -to register a subscriber. Subscribers must implement the -``Doctrine\Common\EventSubscriber`` interface, which means that they must -contain method returning the events they will observe. For this reason, -this tag has no ``event`` attribute, however the ``connection``, -``priority`` and ``lazy`` attributes are available. - -.. code-block:: php - - // src/App/EventSubscriber/MongoDB/ProductSubscriber.php - namespace App\EventSubscriber\MongoDB; - - use App\Document\Product; - use Doctrine\Common\EventSubscriber; - - class ProductSubscriber implements EventSubscriber - { - public function getSubscribedEvents() - { - return [ - // List events to subscribe - ]; - } - } - -.. configuration-block:: - - .. code-block:: yaml + App\EventListener\SearchIndexer: + tags: + - + name: 'doctrine_mongodb.odm.event_listener' + # this is the only required option for the lifecycle listener tag + event: 'postPersist' - # config/services.yaml - services: + # listeners can define their priority in case multiple subscribers or listeners are associated + # to the same event (default priority = 0; higher numbers = listener is run earlier) + priority: 500 - App\EventSubscriber\MongoDB\: - resource: '../src/EventSubscriber/MongoDB/*' - tags: - - { name: doctrine_mongodb.odm.event_subscriber } + # you can also restrict listeners to a specific Doctrine connection + connection: 'default' .. code-block:: xml - + xmlns:doctrine="http://symfony.com/schema/dic/doctrine"> - - - + + + + + + @@ -170,7 +86,4 @@ this tag has no ``event`` attribute, however the ``connection``, event(s). For this reason, the aforementioned tags have no ``method`` attribute. -.. _`event dispatcher`: https://symfony.com/doc/current/components/event_dispatcher.html .. _`Event Documentation`: https://www.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/events.html -.. _`tagging`: https://symfony.com/doc/current/service_container/tags.html -.. _`autoconfiguration`: https://symfony.com/doc/current/service_container.html#the-autoconfigure-option diff --git a/UPGRADE-5.0.md b/UPGRADE-5.0.md index 0d889989..53615cea 100644 --- a/UPGRADE-5.0.md +++ b/UPGRADE-5.0.md @@ -11,3 +11,5 @@ UPGRADE FROM 4.x to 5.0 removed without replacement. * The `Doctrine\Bundle\MongoDBBundle\Command\DoctrineODMCommand` class is now `@internal`, you should not extend from this class. +* `Doctrine\Bundle\MongoDBBundle\EventSubscriber\EventSubscriberInterface` has + been removed. Use the `#[AsDocumentListener]` attribute instead.