diff --git a/Resources/doc/event-listeners.rst b/Resources/doc/event-listeners.rst new file mode 100644 index 000000000..eee99a6a3 --- /dev/null +++ b/Resources/doc/event-listeners.rst @@ -0,0 +1,103 @@ +Event Listeners +=============== + +In opposite to :doc:`Entity Listeners `, Event listeners +are services that listen for all entities in your application. + +See https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#implementing-event-listeners +for more info on event listeners. + +To register a service to act as an event listener you have to tag it with the +``doctrine.event_listener`` tag: + +Starting with Doctrine bundle 2.8, you can use the ``AsDoctrineListener`` +attribute to tag the service. + +.. configuration-block:: + + .. code-block:: php-attributes + + // src/App/EventListener/SearchIndexer.php + namespace App\EventListener; + + use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener; + use Doctrine\ORM\Event\LifecycleEventArgs; + + #[AsDoctrineListener('postPersist'/*, 500, 'default'*/)] + class SearchIndexer + { + public function postPersist(LifecycleEventArgs $event): void + { + // ... + } + } + + .. code-block:: yaml + + # config/services.yaml + services: + # ... + + App\EventListener\SearchIndexer: + tags: + - + name: 'doctrine.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 + + + + + + + + + + + + + + + .. code-block:: php + + // config/services.php + namespace Symfony\Component\DependencyInjection\Loader\Configurator; + + use App\EventListener\SearchIndexer; + + return static function (ContainerConfigurator $configurator) { + $services = $configurator->services(); + + // listeners are applied by default to all Doctrine connections + $services->set(SearchIndexer::class) + ->tag('doctrine.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', + ]) + ; + }; diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst index 1bacaa60f..f4bc0c18d 100644 --- a/Resources/doc/index.rst +++ b/Resources/doc/index.rst @@ -8,5 +8,6 @@ configuration options, console commands and even a web debug toolbar collector. installation entity-listeners + event-listeners custom-id-generators configuration