Un contrôleur de création de commande qui envoie un email de confirmation, met à jour un index de recherche et notifie un webhook partenaire, tout cela de façon synchrone dans la même requête HTTP, est un contrôleur qui va finir par échouer pour de mauvaises raisons. Si le service d'email est lent ou momentanément indisponible, c'est toute la commande qui échoue aux yeux du client, alors que la commande elle-même a parfaitement été enregistrée en base. Symfony Messenger résout ce couplage en introduisant un bus de messages entre l'action métier et ses effets secondaires, mais le découplage introduit ses propres pièges si on ne configure pas correctement la fiabilité de la livraison.

Le mécanisme : bus, enveloppe, transport et handler

Messenger repose sur quatre concepts qui s'articulent clairement. Un message est un objet PHP simple, immuable, qui décrit une intention ou un fait (OrderWasPlaced, SendOrderConfirmationEmail). Un handler est une classe ou méthode qui sait traiter ce message. Un bus reçoit le message, l'enveloppe dans un Envelope qui porte des métadonnées (stamps), et le fait transiter par une chaîne de middleware avant de l'acheminer vers un transport, qui décide s'il est traité immédiatement (transport sync) ou mis en file pour un traitement différé (transport Doctrine, Redis, AMQP/RabbitMQ).

// src/Message/SendOrderConfirmationEmail.php
final class SendOrderConfirmationEmail
{
    public function __construct(
        public readonly int $orderId,
    ) {
    }
}
// src/MessageHandler/SendOrderConfirmationEmailHandler.php
#[AsMessageHandler]
final class SendOrderConfirmationEmailHandler
{
    public function __construct(
        private OrderRepository $orders,
        private MailerInterface $mailer,
    ) {
    }

    public function __invoke(SendOrderConfirmationEmail $message): void
    {
        $order = $this->orders->get($message->orderId);

        $email = (new TemplatedEmail())
            ->to($order->customerEmail)
            ->subject(sprintf('Confirmation de votre commande #%d', $order->id))
            ->htmlTemplate('emails/order_confirmation.html.twig')
            ->context(['order' => $order]);

        $this->mailer->send($email);
    }
}
// dans le contrôleur
public function create(CreateOrderRequest $request, MessageBusInterface $bus): Response
{
    $order = $this->orderService->place($request->toDto());

    $bus->dispatch(new SendOrderConfirmationEmail($order->id));

    return $this->json(['id' => $order->id], Response::HTTP_CREATED);
}

La configuration dans config/packages/messenger.yaml décide du routage : quel transport reçoit quel type de message.

# config/packages/messenger.yaml
framework:
    messenger:
        failure_transport: failed
        transports:
            async: '%env(MESSENGER_TRANSPORT_DSN)%'
            failed: 'doctrine://default?queue_name=failed'
        routing:
            App\Message\SendOrderConfirmationEmail: async

Sans cette ligne de routing, le message resterait traité en synchrone via le transport sync implicite, annulant tout l'intérêt du découplage.

Diagnostiquer les problèmes de fiabilité

Le premier réflexe en production est de vérifier que des workers tournent réellement. Un message routé vers un transport asynchrone n'est traité que si un process messenger:consume l'écoute :

php bin/console messenger:consume async --time-limit=3600 --memory-limit=256M

Sans supervision (Supervisor, systemd avec Restart=always, ou un orchestrateur de conteneurs), ce process meurt silencieusement et les messages s'accumulent dans la file sans qu'aucune erreur applicative ne le signale. La commande messenger:stats (ou l'inspection directe de la table messenger_messages pour le transport Doctrine) permet de vérifier que la file ne grossit pas indéfiniment.

Pour les messages qui échouent après épuisement des tentatives, le transport d'échec dédié (failed) les isole plutôt que de les perdre :

php bin/console messenger:failed:show
php bin/console messenger:failed:show 42 -vv
php bin/console messenger:failed:retry 42

C'est la différence entre un message perdu silencieusement et un message consultable, dont on peut lire la trace d'exception exacte avant de décider de le rejouer ou de le purger.

La configuration de fiabilité : retries et idempotence

Par défaut, un handler qui lève une exception déclenche une stratégie de retry configurable par transport, avec un délai exponentiel :

framework:
    messenger:
        transports:
            async:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                retry_strategy:
                    max_retries: 3
                    delay: 1000
                    multiplier: 2
                    max_delay: 0

Ce mécanisme suppose que le handler est idempotent : le rejouer plusieurs fois avec le même message ne doit pas produire d'effet cumulatif indésirable. Un handler qui envoie un email n'est pas naturellement idempotent (un retry après un succès partiel, par exemple une exception levée après l'envoi mais avant la confirmation au bus, peut renvoyer l'email en double). La parade courante est de journaliser l'identifiant du message traité dans une table dédiée, et de vérifier cette table en entrée de handler avant d'exécuter l'effet de bord :

public function __invoke(SendOrderConfirmationEmail $message): void
{
    if ($this->processedMessages->wasHandled($message, __CLASS__)) {
        return;
    }

    // ... envoi de l'email ...

    $this->processedMessages->markHandled($message, __CLASS__);
}

Les compromis du passage à l'asynchrone

Découpler via Messenger introduit une cohérence éventuelle là où tout était auparavant transactionnel et immédiat. Trois conséquences à anticiper explicitement avec l'équipe produit, pas seulement techniquement :

L'ordre de traitement n'est pas garanti entre plusieurs workers consommant la même file en parallèle. Si un cas d'usage exige un ordre strict (par exemple des événements de changement de statut qui doivent être appliqués dans l'ordre chronologique), il faut soit un seul consommateur dédié à ce flux, soit encoder une version ou un numéro de séquence dans le message pour que le handler puisse rejeter ou réordonner les messages arrivés hors séquence.

L'évolution du schéma des messages doit rester rétrocompatible pendant un déploiement progressif : un message sérialisé par l'ancienne version du code peut rester en file au moment où la nouvelle version démarre. Ajouter une propriété obligatoire sans valeur par défaut casse la désérialisation des messages en attente.

La surveillance devient indispensable : sans métriques sur la taille des files, l'âge du plus vieux message en attente et le taux d'échec, un ralentissement du traitement passe inaperçu jusqu'à ce qu'un utilisateur se plaigne de ne jamais recevoir sa confirmation.

Quand retry et idempotence ne suffisent pas

Le piège le plus subtil concerne la cohérence entre l'écriture en base de données et l'émission du message. Dispatcher un message après avoir committé une transaction Doctrine expose à une fenêtre où l'écriture a réussi mais le processus crash avant le dispatch : le message n'est jamais émis, et aucun mécanisme de Messenger ne peut le rattraper puisqu'il n'a jamais existé. Dispatcher avant le commit, à l'inverse, expose au risque inverse si la transaction est finalement annulée après l'envoi.

La solution robuste est le pattern outbox : écrire l'intention de message dans une table de la même base, dans la même transaction que l'écriture métier, puis laisser un processus séparé lire cette table et l'acheminer vers le vrai transport. Le transport Doctrine de Messenger, utilisé comme file d'attente stockée dans la même base de données que les entités métier, se comporte déjà comme une forme d'outbox si le dispatch() est appelé à l'intérieur de la même transaction Doctrine que l'écriture : l'insertion du message dans messenger_messages est alors atomique avec l'écriture métier, tandis que l'acheminement final vers un transport externe (RabbitMQ, SQS) devient une étape séparée, rejouable.

Tester le dispatch sans worker réel

Un test fonctionnel qui dépend d'un vrai worker messenger:consume tournant en arrière-plan est lent et fragile. Symfony permet de router les messages vers un transport in-memory en environnement de test, qui stocke les messages dispatchés sans les acheminer réellement, et expose une API pour les inspecter :

# config/packages/test/messenger.yaml
framework:
    messenger:
        transports:
            async: 'in-memory://'
public function testOrderCreationDispatchesConfirmationEmail(): void
{
    $client = static::createClient();
    $client->request('POST', '/orders', ['json' => [
        'customerId' => 1,
        'items' => [['sku' => 'ABC-123', 'quantity' => 2]],
    ]]);

    self::assertResponseStatusCodeSame(201);

    $transport = self::getContainer()->get('messenger.transport.async');
    self::assertCount(1, $transport->getSent());

    $envelope = $transport->getSent()[0];
    self::assertInstanceOf(SendOrderConfirmationEmail::class, $envelope->getMessage());
}

Ce test vérifie que le message a bien été dispatché avec le bon contenu, sans dépendre d'un vrai transport Doctrine ou AMQP, ni d'un délai réseau. C'est une vérification du contrat entre le contrôleur et le bus, complémentaire à un test unitaire du handler lui-même qui, lui, vérifie l'effet de bord (l'email réellement envoyé) indépendamment du bus.

En bref

Messenger résout le couplage synchrone, mais il transforme une garantie de cohérence immédiate en une garantie de livraison éventuelle qu'il faut configurer explicitement : transport d'échec, stratégie de retry, idempotence des handlers, et supervision des workers ne sont pas des options secondaires, ce sont les conditions sans lesquelles le découplage se contente de déplacer la perte de données ailleurs dans le système, là où elle est moins visible.