symfony-messenger

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

1. Create the message as a plain readonly class that carries IDs, never entities.
2. Write the handler with #[AsMessageHandler] and a typed __invoke(): refetch by ID, skip work already done.
3. Route the message with #[AsMessage('async')] or the routing key, and declare the transport DSN in messenger.yaml.
4. Set retry_strategy and failure_transport on the transport.
5. Consume with messenger:consume async -vv, bounded by --limit, --memory-limit, or --time-limit.
6. 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

• reference.md