Skip to content
Tutorials Center
My learning

Topics

Lesson 45 of 62 ยท Events, Messaging and Console

Messenger: Messages and Handlers

Run work in the background with Symfony Messenger: messages, handlers, buses, transports, workers, retries and the failure transport, with runnable stand-ins.

Some work should not happen while a visitor waits: generating a PDF, resizing an image, sending a hundred emails, calling a slow API. The classic answer is a queue: the web request drops a note ("please build report 42") and returns immediately, and a separate worker process picks the note up later. Symfony's Messenger component is that queue, plus a clean way to structure the code on both sides.

This lesson explains the vocabulary (message, handler, bus, transport, worker), shows the real configuration, and then rebuilds a bus, a queue, a worker with retries and a failure transport in plain PHP. It builds on events and the service container.

The moving parts

  • A message is a plain PHP object that says what should happen. It has no behaviour: only data.
  • A handler is a service that does the work for one message class.
  • The message bus (MessageBusInterface) receives a message with dispatch() and decides what to do with it.
  • A transport is where messages wait: a database table, Redis, RabbitMQ, or just memory. Messages not routed to a transport are handled immediately, in the same process.
  • A worker is a long-running console command that reads messages from a transport and gives them to handlers.
flowchart LR
    C["Controller<br/>dispatch(new GenerateReport(42))"] --> B["Message bus"]
    B -->|"no transport routed"| H1["Handler runs now<br/>(synchronous)"]
    B -->|"routed to 'async'"| T["Transport<br/>(queue)"]
    T --> W["Worker<br/>messenger:consume async"]
    W --> H2["Handler runs later"]
    W -->|"gives up after retries"| F["Failure transport"]

The same dispatch call can be synchronous or asynchronous; routing configuration decides which.

That last point is the key design idea: your controller always writes $bus->dispatch(...). Whether the work happens now or in a worker is a configuration choice that you can change without touching the controller.

Messages and handlers

PHP
// src/Message/GenerateReport.php (real Symfony, read-only)
namespace App\Message;

final class GenerateReport
{
    public function __construct(
        public readonly int $reportId,
    ) {
    }
}
PHP
// src/MessageHandler/GenerateReportHandler.php (real Symfony, read-only)
namespace App\MessageHandler;

use App\Message\GenerateReport;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class GenerateReportHandler
{
    public function __construct(private ReportBuilder $builder)
    {
    }

    public function __invoke(GenerateReport $message): void
    {
        $this->builder->build($message->reportId);
    }
}

Symfony finds the message class from the type of the argument of __invoke(). The handler is an ordinary autowired service, so it can take Doctrine, a mailer, anything. In the controller:

PHP
// real Symfony, read-only
use Symfony\Component\Messenger\MessageBusInterface;

#[Route('/reports/{id}/generate', methods: ['POST'])]
public function generate(int $id, MessageBusInterface $bus): Response
{
    $bus->dispatch(new GenerateReport($id));

    return $this->redirectToRoute('report_show', ['id' => $id]);
}

Put identifiers in messages, not entities. A message may sit in a queue for minutes and is serialized when stored, so the handler should load a fresh copy of the data by id. This also keeps messages small and safe to deserialize.

Transports and routing

Without configuration the bus is synchronous: the handler runs inside dispatch(). To make it asynchronous you define a transport and route messages to it:

YAML
# config/packages/messenger.yaml (real Symfony, read-only)
framework:
    messenger:
        failure_transport: failed

        transports:
            async:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                retry_strategy:
                    max_retries: 3
                    delay: 1000
                    multiplier: 2
            failed: 'doctrine://default?queue_name=failed'

        routing:
            'App\Message\GenerateReport': async
DOTENV
# .env (real Symfony, read-only)
MESSENGER_TRANSPORT_DSN=doctrine://default

The DSN chooses the technology. doctrine://default stores messages in a table in your existing database (the easiest start), redis:// and amqp:// use Redis or RabbitMQ, in-memory:// is for tests, and sync:// forces synchronous handling. Messages are serialized when sent to a transport and deserialized by the worker, which is why plain data objects are best.

Running the worker

A worker is started from the console and keeps running:

Terminal
# real Symfony, read-only
php bin/console messenger:consume async -vv

In production a process manager such as Supervisor or systemd keeps the worker alive and restarts it. Workers are long-lived PHP processes, so they keep objects in memory; after you deploy new code you must restart them (php bin/console messenger:stop-workers asks them to finish the current message and exit, and the process manager starts fresh ones). Options such as --time-limit=3600 and --memory-limit=128M make a worker exit cleanly and restart on a schedule, which contains memory leaks.

Useful companions: messenger:setup-transports creates the queue table or exchange, and messenger:stats shows how many messages are waiting.

Retries and the failure transport

Handlers fail: a network call times out, a database is briefly down. If a handler throws, the worker does not lose the message. With the strategy above it retries up to max_retries times, waiting delay milliseconds before the first retry and multiplying the wait each time. With delay: 1000 and multiplier: 2 the waits are 1 s, 2 s and 4 s. Note that max_retries: 3 means three retries after the first attempt, so four attempts in total.

When the retries run out, the message moves to the failure transport (failed above) instead of vanishing. You can inspect and replay it:

Terminal
# real Symfony, read-only
php bin/console messenger:failed:show
php bin/console messenger:failed:retry
php bin/console messenger:failed:remove 12

Two exception classes let a handler steer this behaviour. Throw UnrecoverableMessageHandlingException when retrying is pointless (the report no longer exists) and the message goes straight to the failure transport. Throw RecoverableMessageHandlingException to force a retry even when the retry limit would otherwise stop it (the limit is bypassed, so use it with care). Any other exception counts toward the normal retry strategy.

Because a message can run more than once (a retry, or a worker that crashed after the work but before acknowledging), handlers should be idempotent: running them twice must not do harm. Check "is this report already built?" at the start.

A bus you can run

Real Messenger needs Composer packages and a database, so here is a plain-PHP stand-in. It finds each handler's message type with reflection, like the real attribute-based wiring, and adds a middleware layer, which is how Messenger itself implements logging and the "send or handle" decision.

PHP A synchronous message bus with middleware (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The message has two handlers, and both run; the middleware wraps the whole thing and sees the result. Dispatching a message with no handler returns an empty list here. (A real command bus throws a NoHandlerForMessageException by default; Messenger tolerates missing handlers only on buses configured as event buses with allow_no_handlers.)

Async, retries and a failure transport you can run

Now the asynchronous half: routing sends the message to a queue, a worker loop drains it, failures are retried with growing delays, and exhausted messages land in a failure queue. The stand-in does not actually wait; it prints the delay the real strategy would use.

PHP Queue, worker, retries and failure transport (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Watch each report: 1 succeeds at once; 2 fails twice and succeeds on the third attempt; 3 fails every time, so after three retries (waits of 1000, 2000 and 4000 ms) it moves to the failure queue; 4 throws the unrecoverable exception and skips retrying altogether. In real Messenger a retried message goes back to the transport with a delay, so other messages are processed while it waits, instead of being retried at the back of the same loop as here.

Practical guidance

  • Start with the Doctrine transport. It needs no new infrastructure. Move to Redis or RabbitMQ when volume demands it.
  • Several workers, several transports. You can route urgent messages to a high transport and run more workers for it than for a bulk low one.
  • Delay and scheduling. Attach a DelayStamp when dispatching to postpone handling, and see Scheduler and Lock for recurring messages.
  • Mail in the background. The Mailer component can send through Messenger, covered in Mailer and Notifier.
  • Test with in-memory:// in the test environment and assert on what was dispatched.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What decides whether a dispatched message is handled immediately or in a worker?

    The code always calls dispatch(). Routing in messenger.yaml selects a transport; without a route the handlers run during dispatch.
  2. 2. With retry_strategy max_retries: 3, how many times can a failing handler run in total?

    The first attempt plus three retries is four attempts. After that the message goes to the failure transport.
  3. 3. Why should a message usually carry an id instead of a full Doctrine entity?

    Queued messages can be stale by the time they run, and serialized entities are fragile. Send the id and reload.
  4. 4. What should a handler throw when retrying can never succeed (for example, the record was deleted)?

    UnrecoverableMessageHandlingException skips the retries and sends the message to the failure transport.
  5. 5. After deploying new code, what must you do with long-running workers?

    A worker is a long-lived PHP process. It will keep running the old code until it is restarted.

Summary

  • A message is a plain data object; a handler (#[AsMessageHandler], __invoke(Message $m)) does the work; MessageBusInterface::dispatch() sends it.
  • Routing in messenger.yaml maps message classes to transports; unrouted messages are handled synchronously.
  • Transports are chosen by DSN (doctrine://, redis://, amqp://, in-memory://, sync://); workers run with messenger:consume.
  • Failed handlers are retried with a growing delay, then moved to the failure transport; you can inspect and replay with messenger:failed:*.
  • Make handlers idempotent, send ids not entities, and restart workers after deploys.

Next up: Console Commands.