diff --git a/EventSubscriber/EventSubscriberInterface.php b/EventSubscriber/EventSubscriberInterface.php
index 7002ae96..1768b16d 100644
--- a/EventSubscriber/EventSubscriberInterface.php
+++ b/EventSubscriber/EventSubscriberInterface.php
@@ -6,6 +6,7 @@
use Doctrine\Common\EventSubscriber;
+/** @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..3f474c2b 100644
--- a/Resources/doc/events.rst
+++ b/Resources/doc/events.rst
@@ -11,17 +11,12 @@ 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.
+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.
-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
@@ -33,133 +28,69 @@ 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.
-.. 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
-
- $definition = new Definition('App\Listener\MyDoctrineListener');
- // ...
- $definition->addTag('doctrine_mongodb.odm.event_listener', [
- 'event' => 'postPersist',
- ]);
- $container->setDefinition('my_doctrine_listener', $definition);
-
-Event Subscribers
------------------
-
-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()
- {
- return [
- // List events to subscribe
- ];
- }
- }
+Starting with DoctrineMongoDBBundle bundle 4.7, you can use the ``#[AsDocumentListener]``
+attribute to tag the service.
.. configuration-block::
- .. code-block:: yaml
-
- # config/services.yaml
- services:
+ .. code-block:: php-attributes
- App\EventSubscriber\MongoDB\:
- resource: '../src/EventSubscriber/MongoDB/*'
- autoconfigure: true
+ // src/App/EventListener/SearchIndexer.php
+ namespace App\EventListener;
- .. code-block:: xml
+ use Doctrine\Bundle\MongoDBBundle\Attribute\AsDocumentListener;
+ use Doctrine\ODM\MongoDB\Event\LifecycleEventArgs;
-
-
-
-
-
-
-
-
-
-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()
+ #[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/*'
+ App\EventListener\SearchIndexer:
tags:
- - { name: doctrine_mongodb.odm.event_subscriber }
+ -
+ name: 'doctrine_mongodb.odm.event_listener'
+ # this is the only required option for the lifecycle listener tag
+ event: 'postPersist'
+
+ # 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
+
+ # you can also restrict listeners to a specific Doctrine connection
+ connection: 'default'
.. code-block:: xml
-
+ xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
-
-
-
+
+
+
+
+
+
@@ -172,5 +103,3 @@ this tag has no ``event`` attribute, however the ``connection``,
.. _`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-4.7.md b/UPGRADE-4.7.md
index fb4a9a42..66a20593 100644
--- a/UPGRADE-4.7.md
+++ b/UPGRADE-4.7.md
@@ -6,6 +6,11 @@ UPGRADE FROM 4.6 to 4.7
* The bundle now requires PHP 8.1 or newer. If you're not running PHP 8.1 yet,
it's recommended that you upgrade to PHP 8.1 before upgrading the bundle.
+## Event Subscriber
+
+* `Doctrine\Bundle\MongoDBBundle\EventSubscriber\EventSubscriberInterface` has
+ been deprecated. Use the `#[AsDocumentListener]` attribute instead.
+
## Fixtures
* The `fixture_loader` configuration option was deprecated and will be removed
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.