Skip to content

Commit

Permalink
Update documentation for AsDocumentListener
Browse files Browse the repository at this point in the history
  • Loading branch information
@GromNaN
GromNaN committed Dec 20, 2023
1 parent f791974 commit 2ee0763
Show file tree
Hide file tree
Showing 3 changed files with 45 additions and 130 deletions.
2 changes: 1 addition & 1 deletion EventSubscriber/EventSubscriberInterface.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
}
169 changes: 41 additions & 128 deletions Resources/doc/events.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<service id="my_doctrine_listener" class="App\Listener\MyDoctrineListener">
<!-- ... -->
<tag name="doctrine_mongodb.odm.event_listener" event="postPersist" />
</service>
.. 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
<!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd">
<services>
<prototype namespace="App\EventSubscriber\MongoDB\" resource="../src/EventSubscriber/MongoDB/*" autoconfigure="true" />
</services>
</container>
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
<!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd">
xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
<services>
<prototype namespace="App\EventSubscriber\MongoDB\" resource="../src/EventSubscriber/MongoDB/*">
<tag name="doctrine_mongodb.odm.event_subscriber" />
</prototype>
<!-- ... -->
<!--
* 'event' is the only required option that defines the lifecycle listener
* 'priority': used when multiple subscribers or listeners are associated to the same event
* (default priority = 0; higher numbers = listener is run earlier)
* 'connection': restricts the listener to a specific MongoDB connection
-->
<service id="App\EventListener\SearchIndexer">
<tag name="doctrine.event_listener"
event="postPersist"
priority="500"
connection="default" />
</service>
</services>
</container>
Expand All @@ -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
4 changes: 3 additions & 1 deletion UPGRADE-5.0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,6 @@ UPGRADE FROM 4.x to 5.0
`Doctrine\Bundle\MongoDBBundle\Command\DoctrineODMCommand` have been
removed without replacement.
* The `Doctrine\Bundle\MongoDBBundle\Command\DoctrineODMCommand` class is now
`@internal`, you should not extend from this class.
`@internal`, you should not extend from this class.
* `Doctrine\Bundle\MongoDBBundle\EventSubscriber\EventSubscriberInterface` has
been removed. Use the `#[AsDocumentListener]` attribute instead.

0 comments on commit 2ee0763

Please sign in to comment.