symfony-messenger · diff
git:20261005.042befb to git:20261005.51f9253
17 added, 12 removed. Audit A to A.
---
name: symfony-messenger
description: Async message handling with Symfony Messenger; configure transports (RabbitMQ, Redis, Doctrine); implement handlers, middleware, and retry strategies
capabilities: [read, search, edit, shell]
tags: [messenger]
# projected by `bun run build` — do not edit by hand
allowed-tools:
- Read
- Glob
- Grep
- Write
- Edit
- Bash
---
# Symfony Messenger (Symfony)
## Use when
- - Implementing asynchronous workflows with Messenger/Scheduler/Cache.
- - Stabilizing retries and failure transports.
+ - 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. Define async contract and delivery semantics.
- 2. Implement idempotent handlers and routing strategy.
- 3. Configure retries, failure transport, and observability.
- 4. Validate success/failure replay scenarios.
+ 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
- - Assume at-least-once delivery, not exactly-once.
- - Keep handlers deterministic and side-effect aware.
- - Surface poison-message handling strategy.
+ - 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
- - Async config/handlers updated.
- - Retry/failure policy decisions.
- - Operational validation evidence.
+ - 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`