/symfony-messenger

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

• 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`