Symfony Messenger (Symfony)
Use when
- Moving slow or failure-prone work out of the request into a message and an
#[AsMessageHandler] handler.
- Choosing a transport (Doctrine, Redis, AMQP,
sync://, in-memory://) and routing messages to it.
- Running, sizing, and restarting workers with
messenger:consume.
- Making handlers safe under redelivery.
Default workflow
- Create the message as a plain
readonly class that carries IDs, never entities.
- Write the handler with
#[AsMessageHandler] and a typed __invoke(): refetch by ID, skip work already done.
- Route the message with
#[AsMessage('async')] or the routing key, and declare the transport DSN in messenger.yaml.
- Set
retry_strategy and failure_transport on the transport.
- Consume with
messenger:consume async -vv, bounded by --limit, --memory-limit, or --time-limit.
- Check the wiring with
debug:messenger and messenger:stats, and use in-memory:// in tests.
Guardrails
- Pass entity IDs, never Doctrine entities: proxies and detached state do not serialize cleanly.
- Delivery is at-least-once: a redelivered message must return quietly, not throw.
PriorityStamp, --fetch-size, --no-reset, and stop_worker_on_signals are marked 8.1+ in the reference: verify the minimum version first.- Restart workers on deploy with
messenger:stop-workers.
Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.
Output contract
- The message, its handler, and the routing and transport configuration.
- The retry and failure transport settings.
- The worker command, and the
debug:messenger or messenger:stats output that proves the wiring.
References
