Symfony 8.2 Messenger Adds Declared Flows, Failure Actions and Sync Retries
- Javier Eguiluz
- 831 reads
Symfony 8.2 lets teams define message sequences, carry context between handlers and manage failures, with new retry support for synchronous messages.

Symfony 8.2 gives Messenger applications a way to describe multi-step work at the point where it starts. With new stamps, developers can carry context through a flow, link its messages for tracing, define ordered steps and dispatch a recovery message when a step fails. The practical change is architectural: handlers can focus more closely on their own work instead of each handler needing to know which message should run next.

That can simplify processes such as charging a card before shipping an order, or processing a podcast before optimizing and releasing it. Previously, developers commonly connected these stages by having each handler dispatch the next message. That approach works, but the sequence is spread across handlers. Symfony 8.2 lets the initiating dispatch describe more of that sequence in one place.
Carry context without adding it to every message
Messenger handlers often dispatch follow-up messages with fresh envelopes. Context attached to the first message, such as a tenant identifier, would not automatically follow. Applications therefore tended to put that data directly on each message or pass it along through handler code.
Symfony 8.2 introduces PropagatedStampInterface. A stamp implementing the interface is copied to messages dispatched while handling the message that carries it. In practice, a handler can dispatch work for individual catalog rows without knowing about tenant context; the row handlers can still receive the tenant stamp as an argument. Handlers can also receive stamps or the full Envelope after the message argument.
This keeps cross-cutting context in Messenger’s envelope instead of duplicating it across message classes. It’s useful for values that need to travel with work through several handlers, though teams still need to decide which context belongs in a propagated stamp and ensure that handlers interpret it consistently.
Trace related messages with identity stamps
For debugging a flow, knowing that several messages are related can matter as much as knowing what each one does. Set identity_stamps to true in Messenger configuration and Symfony adds three identifiers: a message ID, a correlation ID shared by the flow, and a causation ID identifying the message that triggered a follow-up.
Message IDs remain stable across retries and replays. That gives logs and other diagnostic tooling a way to refer to the same message through those operations. Correlation IDs group messages in a flow, while causation IDs show the direct link from a handled message to work it dispatched. Handlers can receive these stamps as arguments, which makes it possible to add the identifiers to application logs.

The option is off by default because the stamps change serialized envelopes. Teams using serialized messages should account for that change when considering deployment compatibility. Identity stamps are also required by the Messenger inbox, so applications adopting the inbox need to enable them.
Put ordered steps on the initial dispatch
ChainStamp lets an application specify a sequence of messages together. Messenger dispatches each step only after all handlers for the preceding step have finished. A podcast flow, for instance, can declare processing, optimization and release at its starting point rather than encoding each transition in the handler for the step before it.
Individual steps can still carry their own envelope stamps. That lets a flow apply options such as a delay to one message without changing the others. The remaining steps travel with the current message, so if a step is retried, the chain can continue from that point once handling succeeds.
Routing and failure behavior matter when adopting chains. A step without explicit routing uses the transport from which the preceding step was received, and each step is retried independently. If a step fails, the chain stops. This gives teams a clear sequence, but it also means they should check transport configuration and decide what a stopped flow requires operationally.
Attach a recovery action to a chain
DispatchOnFailureStamp describes a message to dispatch when the stamped message fails permanently. For worker processing, that happens after retries are exhausted; during synchronous dispatch, it happens when an exception is thrown. Applied to a chain, the stamp passes from step to step, so the recovery message can be dispatched once if any step fails.
For example, a flow can charge a card and then ship an order, with a cancellation message attached as the failure action. Its handler can receive a FailedMessageStamp and ErrorDetailsStamp to inspect the message that failed and the associated error details. The failed message goes to the failure transport only if Messenger can’t dispatch the recovery message. That distinction is useful when recovery work is part of the application’s normal process, but teams should make sure the recovery handler itself is monitored and can be retried appropriately.
Retries for synchronous messages
Before this release, Messenger’s retry and failure transport behavior applied to messages handled by workers. A message sent through sync://, such as a webhook handled during a request, did not get those features; retry strategy and failure transport settings were ignored for that path.
Symfony 8.2 adds retry and failure_transport options for the synchronous transport. When enabled, Messenger retries failures immediately, without using the retry strategy’s delays. If the message still fails, Messenger sends it to the configured failure transport instead of throwing the exception. Teams can then inspect and retry it with the familiar messenger:failed:show and messenger:failed:retry commands.
Immediate retries may be suitable for request-time work where the application needs a bounded attempt before handing a failure to an operator or later process. They don’t provide a pause between attempts, so the configured retry count and the request’s handling path deserve attention.
Configure stamps on scheduled tasks
Symfony 8.2 also lets #[AsCronTask] and #[AsPeriodicTask] specify stamps directly. The attribute’s stamps option accepts stamp class names and, where needed, constructor arguments. A scheduled report can therefore attach a delay stamp or a tenant stamp without requiring a custom schedule provider.
There’s a transport condition: stamps used when sending messages, such as DelayStamp, apply only when the task goes through a transport. That happens through the task’s transports setting or use_messenger_routing.
Taken together, these changes make Messenger flows easier to declare and inspect, while adding recovery and retry behavior to paths that previously lacked it. The main migration checks are serialized envelope compatibility, transport routing for chain steps, and how immediate retries behave in synchronous request handling.