An order creation controller that synchronously sends a confirmation email, updates a search index, and notifies a partner webhook, all within the same HTTP request, is a controller that will eventually fail for the wrong reasons. If the email provider is slow or briefly unavailable, the entire order looks like it failed from the client's point of view, even though the order itself was written to the database just fine. Symfony Messenger solves this coupling by introducing a message bus between the business action and its side effects, but decoupling brings its own pitfalls if delivery reliability isn't configured deliberately.

The mechanism: bus, envelope, transport and handler

Messenger is built around four concepts that fit together cleanly. A message is a plain, immutable PHP object describing an intent or a fact (OrderWasPlaced, SendOrderConfirmationEmail). A handler is a class or method that knows how to process that message. A bus receives the message, wraps it in an Envelope carrying metadata (stamps), and routes it through a chain of middleware before handing it to a transport, which decides whether it's processed immediately (the sync transport) or queued for later processing (a Doctrine, Redis, or AMQP/RabbitMQ transport).

// 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('Order #%d confirmation', $order->id))
            ->htmlTemplate('emails/order_confirmation.html.twig')
            ->context(['order' => $order]);

        $this->mailer->send($email);
    }
}
// inside the controller
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);
}

The configuration in config/packages/messenger.yaml decides the routing: which transport receives which message type.

# 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

Without that routing line, the message would still be handled synchronously through the implicit sync transport, defeating the whole point of decoupling it.

Diagnosing reliability problems

The first thing to check in production is whether workers are actually running. A message routed to an asynchronous transport only gets processed if a messenger:consume process is listening for it:

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

Without supervision (Supervisor, systemd with Restart=always, or a container orchestrator), that process dies silently and messages pile up in the queue with no application-level error signaling it. The messenger:stats command (or direct inspection of the messenger_messages table for the Doctrine transport) lets you check whether the queue is growing unbounded.

For messages that fail after exhausting their retries, a dedicated failure transport (failed) isolates them instead of losing them outright:

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

That's the difference between a message silently lost and a message you can inspect, reading its exact exception trace before deciding to replay or discard it.

Reliability configuration: retries and idempotency

By default, a handler that throws an exception triggers a per-transport, configurable retry strategy with exponential backoff:

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

This mechanism assumes the handler is idempotent: replaying it several times with the same message must not produce an undesirable cumulative effect. A handler that sends an email is not naturally idempotent (a retry after a partial success, say an exception thrown after sending but before acknowledging back to the bus, can resend the same email twice). The common guard is to log the processed message's identifier in a dedicated table, and check that table at the top of the handler before running the side effect:

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

    // ... send the email ...

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

The tradeoffs of going asynchronous

Decoupling through Messenger introduces eventual consistency where everything used to be transactional and immediate. Three consequences worth surfacing explicitly with product stakeholders, not just engineers:

Processing order isn't guaranteed across multiple workers consuming the same queue in parallel. If a use case requires strict ordering (say, status-change events that must be applied chronologically), you need either a single dedicated consumer for that flow, or a version/sequence number encoded in the message so the handler can reject or reorder out-of-sequence messages.

Message schema evolution has to stay backward compatible across a rolling deployment: a message serialized by the old code version can still be sitting in the queue when the new version starts up. Adding a required property with no default breaks deserialization of messages already waiting.

Monitoring becomes mandatory: without metrics on queue depth, the age of the oldest pending message, and the failure rate, a slowdown in processing goes unnoticed until a user complains they never received their confirmation.

When retries and idempotency aren't enough

The subtlest trap concerns consistency between the database write and the message dispatch. Dispatching a message after committing a Doctrine transaction exposes a window where the write succeeded but the process crashes before dispatch() runs: the message is never sent, and no Messenger mechanism can recover it since it never existed in the first place. Dispatching before the commit exposes the opposite risk if the transaction ends up being rolled back after the message was already sent.

The robust fix is the outbox pattern: write the message intent into a table in the same database, inside the same transaction as the business write, then let a separate process read that table and forward it to the real transport. Messenger's Doctrine transport, used as a queue stored in the same database as the business entities, already behaves like a form of outbox when dispatch() is called inside the same Doctrine transaction as the business write: inserting the message into messenger_messages becomes atomic with the business write, while final delivery to an external transport (RabbitMQ, SQS) becomes a separate, replayable step.

Testing dispatch without a real worker

A functional test that depends on a real messenger:consume worker running in the background is slow and brittle. Symfony lets you route messages to an in-memory transport in the test environment, which stores dispatched messages without actually delivering them, and exposes an API to inspect them:

# 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());
}

This test verifies that the message was dispatched with the right content, without depending on a real Doctrine or AMQP transport, or any network delay. It checks the contract between the controller and the bus, complementing a unit test of the handler itself, which separately verifies the side effect (the email actually sent) independent of the bus.

Takeaway

Messenger solves synchronous coupling, but it trades an immediate consistency guarantee for an eventual delivery guarantee that has to be configured explicitly: a failure transport, a retry strategy, idempotent handlers, and supervised workers aren't secondary options, they're the conditions without which decoupling just moves data loss somewhere else in the system, where it's harder to see.