Architecture Pub/Sub et rôle d'EventDispatcher

EventDispatcher est l'implémentation Symfony du patron Observateur — un mécanisme de découplage entre celui qui émet un signal et ceux qui y réagissent.

Quand tu ouvres un fichier de conf Symfony et que tu vois kernel.request, kernel.response ou security.interactive_login, tu regardes un bus d'événements à l'œuvre. Chaque composant émet des signaux ; n'importe quel autre composant peut y répondre — sans que l'émetteur sache qui écoute.

PSR-14 — la spec commune

Symfony implémente PSR-14, la spécification PHP pour les bus d'événements. Trois interfaces la composent :

EventDispatcher dans l'écosystème Symfony

Tu ne l'utilises pas directement dans le code métier, mais il est partout :

• HttpKernel — cycle requête/réponse entier basé sur des events (KernelEvents)
• Security — security.interactive_login, security.logout
• Form — form.pre_submit, form.submit, form.post_submit
• Workflow — transitions, entrées, sorties d'états
• Doctrine — lifecycle callbacks convertis en events

Flux d'un dispatch

Quand tu appelles $dispatcher->dispatch($event), voici ce qui se passe dans l'ordre :

Chaque listener reçoit trois arguments dans cet ordre : l'event lui-même (modifiable), le nom de l'event (string), et le dispatcher (pour re-dispatcher si besoin).

Lance la simulation pour visualiser ce flux :

addListener et la gestion des priorités

addListener() est la brique de base — elle place un callable dans la file d'un événement avec une priorité.

addListener() est la méthode fondamentale pour enregistrer un listener. Elle prend trois paramètres : le nom de l'événement, le callable à appeler, et la priorité.

$dispatcher->addListener(
    OrderPlacedEvent::class,  // nom de l'event (FQCN recommandé)
    function (OrderPlacedEvent $event): void {
        // traitement
    },
    50  // priorité, défaut = 0
);

Stockage interne et tri

En interne, EventDispatcher stocke les listeners dans un tableau à deux niveaux :

Avant d'appeler les listeners, le dispatcher trie par priorité décroissante via krsort() : la priorité 100 est appelée avant 50, avant 0, avant -100.

Les méthodes de consultation

Invalidation du cache interne

EventDispatcher maintient deux caches internes ($sorted et $optimized) pour éviter de retrier à chaque dispatch. Ces caches sont invalidés automatiquement à chaque appel à addListener() ou removeListener().

Signature complète d'un listener

Le dispatcher appelle chaque listener avec trois arguments :

function (
    $event,       // l'objet event (type dépend de l'event)
    string $eventName,  // le nom de l'event tel qu'enregistré
    EventDispatcherInterface $dispatcher  // le dispatcher lui-même
): void

En pratique, la plupart des listeners ne déclarent que le premier argument. PHP transmet les arguments supplémentaires mais ils sont ignorés si la signature ne les déclare pas.

EventSubscriberInterface — les 3 formes

Un subscriber déclare ses abonnements en une seule méthode statique — c'est le listener centralisé.

Un subscriber est une classe qui regroupe plusieurs listeners liés en un seul endroit. Elle implémente EventSubscriberInterface et déclare ses abonnements via une méthode statique.

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

final class OrderSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            OrderPlacedEvent::class  => 'onOrderPlaced',
            OrderShippedEvent::class => ['onOrderShipped', 20],
            OrderCancelledEvent::class => [
                ['notifyCustomer', 100],
                ['releaseStock',    50],
            ],
        ];
    }

    public function onOrderPlaced(OrderPlacedEvent $event): void { /* ... */ }
    public function onOrderShipped(OrderShippedEvent $event): void { /* ... */ }
    public function notifyCustomer(OrderCancelledEvent $event): void { /* ... */ }
    public function releaseStock(OrderCancelledEvent $event): void { /* ... */ }
}

Les 3 formes de getSubscribedEvents()

La valeur associée à chaque nom d'event peut prendre trois formes :

Ce que fait addSubscriber() en interne

Quand tu appelles $dispatcher->addSubscriber($sub), le dispatcher itère sur getSubscribedEvents() et appelle addListener() pour chaque entrée. C'est du sucre syntaxique — rien de magique :

// Pseudo-code simplifié de addSubscriber()
foreach ($subscriber::getSubscribedEvents() as $eventName => $params) {
    if (is_string($params)) {
        $this->addListener($eventName, [$subscriber, $params]);
    } elseif (is_string($params[0])) {
        $this->addListener($eventName, [$subscriber, $params[0]], $params[1] ?? 0);
    } else {
        foreach ($params as $listener) {
            $this->addListener($eventName, [$subscriber, $listener[0]], $listener[1] ?? 0);
        }
    }
}

Utilise la simulation ci-dessous pour voir comment chaque forme de getSubscribedEvents() est traduite en appels addListener() :

Créer ses propres événements

Un événement bien conçu est un DTO immutable avec un nom stable — il porte les données dont les listeners ont besoin.

Un event Symfony n'est qu'un objet PHP ordinaire. Mais sa conception influe directement sur la maintenabilité de ton code. Voyons comment créer des events robustes.

La classe de base Event

Symfony fournit Symfony\Contracts\EventDispatcher\Event comme classe de base. Elle implémente StoppableEventInterface et expose deux méthodes :

use Symfony\Contracts\EventDispatcher\Event;

final class OrderPlacedEvent extends Event
{
    public function __construct(
        public readonly Order $order,
        public readonly \DateTimeImmutable $placedAt,
    ) {}
}

Event typé vs GenericEvent

Symfony fournit aussi GenericEvent — un event polyvalent pour les cas simples :

use Symfony\Component\EventDispatcher\GenericEvent;

// GenericEvent : subject + arguments
$event = new GenericEvent($order, ['channel' => 'web']);
$event->getSubject();           // l'objet Order
$event['channel'];              // 'web' (ArrayAccess)
$event->getArgument('channel'); // 'web'

GenericEvent implémente ArrayAccess et IteratorAggregate. C'est pratique pour des scripts ou du prototypage, mais pour du code métier on préfère un event typé :

Nommage des événements

Depuis Symfony 5, la convention recommandée est d'utiliser le FQCN de la classe event comme nom :

// Recommandé (Symfony 5+)
$dispatcher->dispatch(new OrderPlacedEvent($order));
// Le nom est automatiquement OrderPlacedEvent::class

// Ancienne convention (encore valide, moins idiomatique)
const ORDER_PLACED = 'order.placed';
$dispatcher->dispatch(new OrderPlacedEvent($order), self::ORDER_PLACED);

Bonnes pratiques de conception

• Immutabilité — propriétés readonly, pas de setters. Les listeners ne doivent pas modifier l'event, sauf si c'est explicitement leur rôle (ex. GetResponseEvent de HttpKernel).
• Données minimalistes — ne passe que ce dont les listeners ont besoin. Pas besoin de passer tout l'agrégat si un ID suffit.
• Pas de logique — l'event est un DTO, pas un service. Aucune dépendance injectée.
• Nommage au passé — OrderPlacedEvent (quelque chose s'est passé), pas PlaceOrderEvent (qui ressemble à une commande).

StoppableEventInterface — arrêter la propagation

stopPropagation() permet à un listener d'interrompre la chaîne — les listeners suivants ne seront pas appelés.

Imagine une chaîne de contrôle de sécurité à l'aéroport : si un listener détecte un problème, il peut lever la main et dire "je gère ça, pas la peine que les autres continuent". C'est exactement ce que fait stopPropagation().

Comment ça fonctionne dans callListeners()

Dans le code interne de EventDispatcher::callListeners(), après chaque appel à un listener, le dispatcher vérifie :

// Pseudo-code de callListeners()
foreach ($listeners as $listener) {
    $listener($event, $eventName, $this);
    if ($event instanceof StoppableEventInterface && $event->isPropagationStopped()) {
        break;  // on s'arrête ici, les suivants ne sont pas appelés
    }
}

Appeler stopPropagation()

final class AccessCheckListener
{
    public function onRequest(RequestEvent $event): void
    {
        if (!$this->isAuthorized($event->getRequest())) {
            $event->setResponse(new Response('Forbidden', 403));
            $event->stopPropagation();  // les listeners suivants sont ignorés
        }
    }
}

Cas d'usage légitimes

• Validation en chaîne — premier listener qui détecte une erreur stoppe les validations suivantes
• Résolution de réponse — le premier listener qui peut répondre prend la main (pattern chain of responsibility)
• Override de comportement — un listener prioritaire remplace le comportement par défaut des listeners de base priorité

Interaction avec la priorité

La priorité et stopPropagation() interagissent directement. Un listener de priorité 100 peut stopper les listeners de priorité 50, 0, -100. L'inverse est impossible — un listener de priorité 0 ne peut pas stopper ceux de priorité 100 car ils ont déjà été appelés.

Utilise la simulation pour visualiser l'effet de stopPropagation() :

Listener vs Subscriber — guide de choix

Listener et Subscriber ne font pas la même chose — ils répondent à des besoins d'organisation différents.

Listener et Subscriber coexistent dans Symfony. Ils ont des forces différentes — choisir entre les deux est une question d'organisation, pas de performance.

Le listener — simple et ciblé

Un listener est n'importe quel callable enregistré sur un seul event :

// Listener via closure (idéal pour le prototypage)
$dispatcher->addListener(
    OrderPlacedEvent::class,
    static function (OrderPlacedEvent $event): void {
        // logique ici
    },
    50
);

// Listener via attribut PHP (recommandé dans Symfony)
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: OrderPlacedEvent::class, priority: 50)]
final class SendConfirmationEmailListener
{
    public function __invoke(OrderPlacedEvent $event): void
    {
        // logique ici
    }
}

Le subscriber — centralisé et auto-découvert

Un subscriber regroupe la gestion de plusieurs events liés dans une seule classe. Il est auto-découvert par Symfony via autoconfigure :

final class OrderSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            OrderPlacedEvent::class   => ['onPlaced',   100],
            OrderShippedEvent::class  => ['onShipped',   50],
            OrderCancelledEvent::class => 'onCancelled',
        ];
    }
    // méthodes...
}

Tableau de comparaison

Guide de choix

TraceableEventDispatcher — le débugger

En environnement dev, Symfony remplace EventDispatcher par TraceableEventDispatcher — il enregistre tout pour le Profiler.

En environnement de développement, Symfony ne te donne pas l'EventDispatcher standard — il l'enveloppe dans un TraceableEventDispatcher. Chaque dispatch est observé, mesuré et enregistré.

Construction

use Symfony\Component\EventDispatcher\Debug\TraceableEventDispatcher;
use Symfony\Component\Stopwatch\Stopwatch;

$traceable = new TraceableEventDispatcher(
    $realDispatcher,  // le vrai EventDispatcher
    new Stopwatch(),   // pour mesurer le timing
    $logger,           // PSR-3 Logger, optionnel
);

Le mécanisme de wrapping

Quand un dispatch est déclenché, TraceableEventDispatcher exécute en deux temps :

Chaque WrappedListener mesure son propre temps d'exécution via Stopwatch et enregistre s'il a été appelé et si la propagation a été stoppée.

Les méthodes d'inspection

Utilisation dans le Profiler

Ces données alimentent l'onglet Events du Symfony Profiler. Tu y vois la liste de tous les events dispatchés pendant la requête, les listeners appelés pour chacun, leur temps d'exécution, et les listeners non déclenchés. C'est l'outil de debugging principal pour tout comportement bizarre lié aux events.

Désactivation conditionnelle

Pour les tests de performance ou les benchmarks, tu peux désactiver temporairement le traçage via une closure $disabled passée au constructeur. Quand la closure retourne true, le dispatcher se comporte comme un EventDispatcher standard.

$disabled = static fn() => $_SERVER['APP_ENV'] === 'bench';

$traceable = new TraceableEventDispatcher(
    $realDispatcher,
    new Stopwatch(),
    null,
    $disabled,  // 4e paramètre optionnel
);

ImmutableEventDispatcher

ImmutableEventDispatcher est un proxy read-only — il expose le catalogue d'événements sans permettre l'enregistrement de nouveaux listeners.

Parfois tu veux exposer un EventDispatcher à du code qui doit pouvoir écouter des events, mais pas en ajouter de nouveaux. C'est le rôle de ImmutableEventDispatcher : un proxy read-only.

Construction et usage

use Symfony\Component\EventDispatcher\ImmutableEventDispatcher;

// Construire le dispatcher complet
$dispatcher = new EventDispatcher();
$dispatcher->addListener(OrderPlacedEvent::class, $listener);

// Exposer une vue read-only
$immutable = new ImmutableEventDispatcher($dispatcher);

// OK — lire le catalogue
$immutable->hasListeners(OrderPlacedEvent::class);  // true
$immutable->getListeners(OrderPlacedEvent::class);  // [...listeners...]
$immutable->dispatch(new OrderPlacedEvent($order)); // dispatch fonctionne

// KO — écrire lève BadMethodCallException
$immutable->addListener(OrderPlacedEvent::class, $newListener);
// BadMethodCallException: Unmodifiable event dispatchers must not be modified.

Méthodes d'écriture — return type never

Les méthodes d'écriture de ImmutableEventDispatcher ont le return type never : elles lèvent toujours une exception et ne retournent jamais normalement.

Cas d'usage

• Injecter dans du code client non-trusté — une extension tierce peut écouter tes events mais ne peut pas en hijacker d'autres
• Finaliser une configuration — after kernel boot, le conteneur peut exposer un ImmutableEventDispatcher pour garantir que plus aucun listener ne sera ajouté
• Tests — passer un ImmutableEventDispatcher à un composant pour vérifier qu'il ne tente pas d'enregistrer des listeners

Intégration Symfony — DIC, tags, autoconfigure

Dans une application Symfony, EventDispatcher est un service du conteneur — les listeners et subscribers se déclarent via attributs PHP.

Dans une application Symfony, tu n'instancies jamais EventDispatcher manuellement — il vit dans le conteneur. Les listeners et subscribers sont des services comme les autres, enregistrés via des attributs PHP ou des tags YAML.

#[AsEventListener] — la voie moderne

Depuis Symfony 6.3, l'attribut #[AsEventListener] est la façon la plus concise d'enregistrer un listener. Il remplace le tag kernel.event_listener :

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: OrderPlacedEvent::class, priority: 50)]
final class SendConfirmationEmailListener
{
    public function __invoke(OrderPlacedEvent $event): void
    {
        // envoi email...
    }
}

// Plusieurs events sur la même classe (IS_REPEATABLE)
#[AsEventListener(event: OrderPlacedEvent::class,   method: 'onPlaced')]
#[AsEventListener(event: OrderShippedEvent::class,  method: 'onShipped', priority: 30)]
final class OrderNotificationListener
{
    public function onPlaced(OrderPlacedEvent $event): void { /* ... */ }
    public function onShipped(OrderShippedEvent $event): void { /* ... */ }
}

kernel.event_listener tag YAML

La déclaration YAML reste valide. Utile pour des listeners dans des bundles ou des projets qui préfèrent la configuration séparée :

# config/services.yaml
App\EventListener\SendConfirmationEmailListener:
    tags:
        - name: kernel.event_listener
          event: App\Event\OrderPlacedEvent
          method: __invoke
          priority: 50

EventSubscriberInterface et autoconfigure

Toute classe implémentant EventSubscriberInterface est automatiquement tagguée kernel.event_subscriber grâce à autoconfigure: true (activé par défaut dans Symfony). Aucune déclaration manuelle nécessaire.

Plusieurs dispatchers dans le même projet

Symfony permet d'avoir plusieurs instances de EventDispatcher dans le conteneur (par exemple pour isoler des events métier des events framework). Dans ce cas :

# Déclarer un second dispatcher
app.order_dispatcher:
    class: Symfony\Component\EventDispatcher\EventDispatcher

# Cibler ce dispatcher dans un listener
App\Listener\OrderListener:
    tags:
        - name: kernel.event_listener
          event: App\Event\OrderPlacedEvent
          dispatcher: app.order_dispatcher

Synthèse — le guide de décision

EventDispatcher ou Messenger ? Listener ou Subscriber ? Quand stopper ? Le guide de décision.

Tu maîtrises maintenant les pièces du puzzle : listeners, subscribers, priorités, propagation, traceur, proxy read-only, intégration DIC. Il est temps d'assembler un guide de décision clair.

Guide de choix : besoin → outil

EventDispatcher vs Symfony Messenger

C'est la question qui revient souvent. La frontière est la suivante :

4 anti-patterns à éviter

Récapitulatif des classes et interfaces