Symfony Messenger Component

https://github.com/symfony/messenger
Admin
The Messenger component helps applications send and receive messages to/from other applications or...
Tokens:65,120
Snippets:470
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### SetupableTransportInterface with setup() method

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transport.md

Defines a contract for transports that require infrastructure preparation before use. The setup() method is invoked by the messenger:setup-transports command.

```php
interface SetupableTransportInterface
{
    /**
     * Setup the transport.
     */
    public function setup(): void;
}
```

--------------------------------

### Usage example for SendMessageMiddleware

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/send-message-middleware.md

Shows how to instantiate SendMessageMiddleware with a SendersLocator, an EventDispatcher, and allowNoSenders set to false.

```php
use Symfony\Component\Messenger\Middleware\SendMessageMiddleware;
use Symfony\Component\Messenger\Transport\Sender\SendersLocator;

$middleware = new SendMessageMiddleware($sendersLocator, $eventDispatcher, allowNoSenders: false);
```

--------------------------------

### Usage Example

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/message-bus.md

Example of using TraceableMessageBus to wrap a MessageBus and retrieve dispatched messages.

```APIDOC
## Usage Example

### Description
Example of using TraceableMessageBus to wrap a MessageBus and retrieve dispatched messages.

### Code
```php
use Symfony\Component\Messenger\MessageBus;
use Symfony\Component\Messenger\RoutableMessageBus;
use Symfony\Component\Messenger\TraceableMessageBus;

$bus = new MessageBus([$sendMiddleware, $handleMiddleware]);

// debugging wrapper
$tracedBus = new TraceableMessageBus($bus);
$envelope = $tracedBus->dispatch($message, []);
// $tracedBus->getDispatchedMessages() now contains one entry

// routing between named buses
$routable = new RoutableMessageBus($busLocator, fallbackBus: $defaultBus);
```
```

--------------------------------

### Symfony Messenger configuration example

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/configuration.md

Example configuration for the Symfony Messenger component, defining the default bus, buses with middleware, routing rules, transports (AMQP, in-memory, sync), and failure handling options. Use this as a reference when configuring Messenger in a Symfony application.

```php
'messenger' => [
    'default_bus' => 'messenger.bus.default',
    'buses' => [
        'messenger.bus.default' => [
            'default_middleware' => ['enabled' => true, 'allow_no_handlers' => false, 'allow_no_senders' => true],
            'middleware' => [['id' => 'validation']],
        ],
    ],
    'routing' => [
        'App\Message\SendEmail'   => ['amqp'],
        'App\Message\NotifyUser'  => ['amqp', 'redis'],
        '*' => ['amqp'],
    ],
    'transports' => [
        'amqp' => [
            'dsn' => 'amqp://user:***@broker/vhost',
            'retry_strategy' => ['max_retries' => 3, 'delay' => 1000, 'multiplier' => 2],
            'failure_transport' => 'failed',
            'priority' => 10,
        ],
        'failed' => ['dsn' => 'in-memory://?serialize=true'],
        'sync'  => ['dsn' => 'sync://', 'retry' => true],
    ],
    'failure_transport' => 'failed',
    'reject_redelivered_messages' => true,
],
```

--------------------------------

### Set up MessengerBundle with ContainerBuilder and get the bus

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/messenger-bundle.md

Initialize a container, add the MessengerBundle, set the 'messenger.transports' parameter, build the container, and retrieve the default message bus.

```php
use Symfony\Component\Messenger\MessengerBundle;
use Symfony\Component\Messenger\MessageBusInterface;

$container = ContainerBuilder::create()
    ->addBundle(MessengerBundle::class)
    ->setParameter('messenger.transports', [/* configuration */])
    ->build();

$bus = $container->get(MessageBusInterface::class); // the default bus
```

--------------------------------

### Implement ReceiverInterface with get, ack, reject

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/receiver.md

Shows the required methods for a custom receiver: get() returns decoded envelopes, ack() and reject() handle broker acknowledgements. The get() method should yield envelopes wrapped with a TransportMessageIdStamp.

```php
use Symfony\Component\Messenger\Transport\Receiver\ReceiverInterface;
use Symfony\Component\Messenger\Envelope;

final class MyReceiver implements ReceiverInterface
{
    public function get(int $fetchSize = 1): iterable
    {
        // yield $message => Envelope::wrap($message, [new TransportMessageIdStamp($id)])
    }

    public function ack(Envelope $envelope): void { /* broker->ack() */ }
    public function reject(Envelope $envelope): void { /* broker->reject() */ }
}
```

--------------------------------

### Usage of TraceableMessageBus and RoutableMessageBus

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/message-bus.md

Usage example showing how to wrap a MessageBus with TraceableMessageBus for debugging and how to use RoutableMessageBus for routing between named buses.

```php
use Symfony\Component\Messenger\MessageBus;
use Symfony\Component\Messenger\RoutableMessageBus;
use Symfony\Component\Messenger\TraceableMessageBus;

$bus = new MessageBus([$sendMiddleware, $handleMiddleware]);

// debugging wrapper
$tracedBus = new TraceableMessageBus($bus);
$envelope = $tracedBus->dispatch($message, []);
// $tracedBus->getDispatchedMessages() now contains one entry

// routing between named buses
$routable = new RoutableMessageBus($busLocator, fallbackBus: $defaultBus);
```

--------------------------------

### Usage: dispatching with DeduplicateStamp

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/dispatch-after-current-bus-deduplicate-middleware.md

Shows how to dispatch a command with a DeduplicateStamp using a business key and TTL. Requires symfony/lock to be installed.

```php
use Symfony\Component\Messenger\Stamp\DeduplicateStamp;
use Symfony\Component\Messenger\Middleware\DeduplicateMiddleware;

// deduplicate outgoing commands by business key
$bus->dispatch($command, [new DeduplicateStamp('order:'.$orderId, ttl: 300.0)]);
```

--------------------------------

### Usage: instantiating DeduplicateMiddleware

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/dispatch-after-current-bus-deduplicate-middleware.md

Creates a new DeduplicateMiddleware instance with a LockFactory. Requires symfony/lock to be installed; otherwise the bundle removes this middleware.

```php
$middleware = new DeduplicateMiddleware($lockFactory);
// requires symfony/lock to be installed; otherwise the bundle removes this middleware
```

--------------------------------

### Usage with FailedMessageRepository

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/failure.md

Shows how to instantiate FailedMessageRepository and iterate over failed messages using a filter. The example uses the 'failed' transport and removes each envelope after retrieving its ID.

```php
use Symfony\Component\Messenger\Failure\FailedMessageRepository;
use Symfony\Component\Messenger\Failure\FailedMessageFilter;

$repo = new FailedMessageRepository(
    $failureTransports,          // ServiceProviderInterface<ReceiverInterface>
    globalFailureTransportName: 'failed',
    $phpSerializer,              // nullable
    $messageBus,                 // needed for redispatch()
);

foreach ($repo->all('failed', new FailedMessageFilter(class: 'App\Message\SendEmail'), 100) as $envelope) {
    $id = FailedMessageRepository::getMessageId($envelope);
    $repo->remove($envelope, 'failed');
}
```

--------------------------------

### ValidationMiddleware constructor and handle method

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Constructor and handle method signature for ValidationMiddleware. Validates the message with the configured ValidatorInterface and throws ValidationFailedException on violations. Only available when symfony/validator is installed.

```php
public function __construct(private ValidatorInterface $validator) {}
public function handle(Envelope $envelope, StackInterface $stack): Envelope
```

--------------------------------

### Serializer class implementing SerializerInterface and MessageTypeAwareSerializerInterface

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/serializers.md

Symfony Serializer component-based serializer for Messenger envelopes, supporting formats like JSON and XML. The constructor accepts an optional underlying serializer, format, context, and type-to-class map; the map is flipped for encoding so the last name listed for a class is used. encode() reads SerializerStamp context, re-emits original body/headers for decode-failure envelopes, strips NonSendableStampInterface stamps, and writes X-Message-Stamp-<class> headers; decode() requires body/headers/headers.type and wraps failures into MessageDecodingFailedException envelopes. create() throws LogicException when symfony/serializer is not installed.

```php
class Serializer implements SerializerInterface, MessageTypeAwareSerializerInterface
{
    public const MESSENGER_SERIALIZATION_CONTEXT = 'messenger_serialization';

    /**
     * @param array<string, class-string> $typeToClassMap ... The map is flipped to pick the type name
     *        to encode with, so the last name listed for a class is the one that gets sent
     */
    public function __construct(
        ?SymfonySerializerInterface $serializer = null,
        private string $format = 'json',
        private array $context = [],
        private array $typeToClassMap = [],
    ) {}
    public static function create(): self
    public function decode(array $encodedEnvelope): Envelope
    public function getMessageType(array $encodedEnvelope): ?string
    public function encode(Envelope $envelope): array
}
```

--------------------------------

### Worker instantiation and run with options

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/worker.md

Shows how to instantiate a Worker with multiple receivers and run it with options like sleep, time_limit, and fetch_size. The 'queues' option is commented out because it requires receivers implementing QueueReceiverInterface.

```php
use Symfony\Component\Messenger\Worker;
use Symfony\Component\Messenger\RoutableMessageBus;
use Symfony\Component\Messenger\Retry\MultiplierRetryStrategy;
use Symfony\Component\Messenger\Execution\ParallelExecutionStrategy;

$worker = new Worker(
    ['amqp' => $amqpReceiver, 'redis' => $redisReceiver],
    $routableBus,
    $eventDispatcher,
    $logger,
);

$worker->run([
    'sleep' => 1_000_000,
    'time_limit' => 3600,
    // 'queues' => ['fasttrack'],  // only with QueueReceiverInterface receivers
    'fetch_size' => 4,
]);
```

--------------------------------

### TransportFactory usage with DSN support check

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transport.md

Shows how to create a TransportFactory with multiple transport factories, check support for a DSN, and create a transport. Also demonstrates that an unknown scheme throws an InvalidArgumentException with a helpful message.

```php
use Symfony\Component\Messenger\Transport\TransportFactory;

$factory = new TransportFactory([
    $inMemoryFactory,
    $syncFactory,
    $amqpFactory,
]);

if ($factory->supports('amqp://user:pass@broker/vhost', [])) {
    $transport = $factory->createTransport('amqp://user:pass@broker/vhost', ['transport_name' => 'amqp'], $serializer);
}

// unknown scheme → helpful InvalidArgumentException
try {
    $factory->createTransport('carrier-pigeon://x', [], $serializer);
} catch (\Symfony\Component\Messenger\Exception\InvalidArgumentException $e) {
    // "No transport supports Messenger DSN ..."
}
```

--------------------------------

### ReceiverInterface: get, ack, reject methods

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/receiver.md

Defines the contract for a transport receiver: get() pulls a small number of messages (best-effort fetchSize hint), ack() acknowledges a handled envelope, and reject() is called when handling failed and retries are exhausted. All methods throw TransportException on communication issues. Undecodable messages should be returned as envelopes wrapping a MessageDecodingFailedException.

```php
interface ReceiverInterface
{
    /**
     * Receives some messages.
     *
     * ... (intention: return only one, or a "small number" of messages each time)
     *
     * If applicable, the Envelope should contain a TransportMessageIdStamp.
     *
     * If a received message cannot be decoded, the transport should return
     * an Envelope containing a MessageDecodingFailedException so the worker
     * can route it through the usual failure handling path.
     *
     * @param int $fetchSize Best-effort hint about how many messages can be received in one call
     *
     * @return iterable<Envelope>
     *
     * @throws TransportException If there is an issue communicating with the transport
     */
    public function get(/* int $fetchSize = 1 */): iterable;

    /**
     * Acknowledges that the passed message was handled.
     *
     * @throws TransportException If there is an issue communicating with the transport
     */
    public function ack(Envelope $envelope): void;

    /**
     * Called when handling the message failed and it should not be retried.
     *
     * @throws TransportException If there is an issue communicating with the transport
     */
    public function reject(Envelope $envelope): void;
}
```

--------------------------------

### RouterContextMiddleware constructor and handle method

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Constructor and handle method for RouterContextMiddleware. Snapshots the HTTP router request context into a RouterContextStamp on dispatch and re-installs it via RequestContextAwareInterface::runWith() when consumed by a worker (ConsumedByWorkerStamp). Snapshot fields include baseUrl, method, host, scheme, httpPort, httpsPort, pathInfo, queryString.

```php
public function __construct(private RequestContextAwareInterface $router) {}
public function handle(Envelope $envelope, StackInterface $stack): Envelope
```

--------------------------------

### FailedMessageRepository Usage

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/failure.md

Example of using FailedMessageRepository to list, remove, and redispatch failed messages, including error handling.

```APIDOC
## Usage

```php
use Symfony\Component\Messenger\Failure\FailedMessageRepository;
use Symfony\Component\Messenger\Failure\FailedMessageFilter;

$repo = new FailedMessageRepository(
    $failureTransports,          // ServiceProviderInterface<ReceiverInterface>
    globalFailureTransportName: 'failed',
    $phpSerializer,              // nullable
    $messageBus,                 // needed for redispatch()
);

foreach ($repo->all('failed', new FailedMessageFilter(class: 'App\Message\SendEmail'), 100) as $envelope) {
    $id = FailedMessageRepository::getMessageId($envelope);
    $repo->remove($envelope, 'failed');
}
```

Error handling — unknown transports fail loudly:

```php
try {
    $repo->getReceiver('nope');
} catch (\Symfony\Component\Messenger\Exception\InvalidArgumentException $e) {
    // "The \"nope\" failure transport was not found. Available transports are: ..."
}

try {
    $repo->redispatch($envelope); // no message bus injected
} catch (\Symfony\Component\Messenger\Exception\LogicException $e) {
    // "Cannot redispatch a failed message without a message bus."
}
```
```

--------------------------------

### WorkerStartedEvent

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/events.md

Dispatched once before the worker loop starts. Provides access to the worker, the deadline for --time-limit, and the idle timeout.

```APIDOC
## WorkerStartedEvent

### Description
Dispatched once before the worker loop starts. Provides access to the worker, the deadline for --time-limit, and the idle timeout.

### Constructor
- `__construct(Worker $worker, ?float $deadline = null, int $idleTimeout = 1000000)`

### Methods
- `getWorker(): Worker` - Returns the worker instance.
- `getDeadline(): ?float` - Returns the absolute microtime(true) deadline of --time-limit, or null.
- `getIdleTimeout(): int` - Returns the microseconds sleep between idle polls (default 1,000,000).
```

--------------------------------

### supports

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transport.md

Determines whether the factory can handle the given DSN and options.

```APIDOC
## supports

### Description
Checks whether this factory supports the given DSN and options.

### Method
supports

### Signature
`supports(string $dsn, array $options): bool`

### Parameters
- **$dsn** (string) - Required - The DSN to check.
- **$options** (array) - Required - Options to check.

### Return Value
- **bool** - True if the factory supports the DSN, false otherwise.

```

--------------------------------

### DispatchTask constructor and run method

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/execution.md

Constructor and run method signature for the DispatchTask class. The constructor accepts the console command string, a reset interval (default 1), and an optional memory limit. The run method receives a Channel and Cancellation and returns mixed.

```php
public function __construct(
    private readonly string $console,
    private readonly int $resetInterval = 1,
    private readonly ?int $memoryLimit = null,
) {}
public function run(Channel $channel, Cancellation $cancellation): mixed
```

--------------------------------

### ParallelExecutionStrategy class constructor

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/execution.md

Strategy that runs messages on a pool of amphp/parallel context workers with configurable concurrency. Requires the amphp/parallel package. The constructor takes the console entry point path, concurrency limit, reset interval, and optional memory limit.

```php
final class ParallelExecutionStrategy implements MessageExecutionStrategyInterface
{
    public function __construct(
        private readonly string $console,
        private readonly int $concurrencyLimit = 1,
        private readonly int $resetInterval = 1,
        private readonly ?int $memoryLimit = null,
    ) {}
}
```

--------------------------------

### Instantiate HandleMessageMiddleware

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handle-message-middleware.md

Instantiate the HandleMessageMiddleware with a handlers locator and set allowNoHandlers to false. This is the typical usage when adding the middleware to a Messenger bus.

```php
use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware;

$middleware = new HandleMessageMiddleware($handlersLocator, allowNoHandlers: false);
```

--------------------------------

### Parallel execution with ParallelExecutionStrategy

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/worker.md

Shows how to configure a worker with parallel execution using ParallelExecutionStrategy, including concurrency limit and reset interval, and how to shut down the strategy after the worker finishes.

```php
$strategy = new ParallelExecutionStrategy($consolePath, concurrencyLimit: 4, resetInterval: 1);
$worker = new Worker($receivers, $routableBus, $dispatcher, $logger, null, new Clock(), $strategy);
$worker->run();
$strategy->shutdown();
```

--------------------------------

### Catch HandlerFailedException

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handle-message-middleware.md

Catch a HandlerFailedException when dispatching a command. The exception aggregates all handler failures, and getWrappedExceptions() returns an array keyed by handler name. The comment shows an example error message format.

```php
try {
    $bus->dispatch($command);
} catch (\Symfony\Component\Messenger\Exception\HandlerFailedException $e) {
    foreach ($e->getWrappedExceptions() as $handlerName => $failure) {
        // "Handling \"App\\Message\\PlaceOrder\" failed: ..."
    }
}
```

--------------------------------

### Constructing a bus chain programmatically

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Constructs a message bus chain programmatically, using ActivationMiddleware to conditionally activate an inner middleware based on the message type. The bus includes AddDefaultStampsMiddleware, the activation chain, LoggingMiddleware, and a handle middleware.

```php
use Symfony\Component\Messenger\MessageBus;
use Symfony\Component\Messenger\Middleware\ActivationMiddleware;
use Symfony\Component\Messenger\Middleware\LoggingMiddleware;
use Symfony\Component\Messenger\Middleware\MiddlewareInterface;

$chain = new ActivationMiddleware($innerMiddleware, static fn (Envelope $e): bool => $e->getMessage() instanceof ImportantMessage);

$bus = new MessageBus([
    new AddDefaultStampsMiddleware(),
    $chain,
    new LoggingMiddleware($logger),
    $handleMiddleware,
]);
```

--------------------------------

### Catching LogicException for unhandled query

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handle-trait.md

Error handling example: catching LogicException when a query has no registered handler. The exception message indicates the message was handled zero times and exactly one handler is expected.

```php
try {
    $this->handle(new FindUserById($id));
} catch (\Symfony\Component\Messenger\Exception\LogicException $e) {
    // "Message of type ... was handled zero times. Exactly one handler is expected..."
}
```

--------------------------------

### InMemoryTransport usage with DelayStamp

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transports.md

Creates an in-memory transport for testing without serialization. Sends a message with a DelayStamp and asserts the assigned message ID. The get() loop shows that delayed messages are not returned until their availableAt time.

```php
use Symfony\Component\Messenger\Transport\InMemory\InMemoryTransport;

$inMemory = new InMemoryTransport(); // no serialization
$sent = $inMemory->send($envelope->with(new DelayStamp(100)));
assert $sent->last(TransportMessageIdStamp::class)->getId() === 1;

while ($messages = $inMemory->get(10)) { /* delayed messages wait until availableAt */ }
```

--------------------------------

### HandleMessageMiddleware::__construct

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handle-message-middleware.md

Constructor for the HandleMessageMiddleware class. Initializes the middleware with a handlers locator and optional configuration for allowing no handlers, a clock, and an event dispatcher.

```APIDOC
## Constructor: `__construct`

### Description
Initializes the middleware with a handlers locator and optional configuration for allowing no handlers, a clock, and an event dispatcher.

### Method
`__construct`

### Parameters
- **$handlersLocator** (`HandlersLocatorInterface`) - Required - Resolves `HandlerDescriptor`s for the envelope.
- **$allowNoHandlers** (`bool`) - Optional (default: `false`) - When `false`, zero handlers for a message throws `NoHandlerForMessageException`.
- **$clock** (`?ClockInterface`) - Optional (default: `null`) - Clock handed to batch `Acknowledger`s.
- **$dispatcher** (`?EventDispatcherInterface`) - Optional (default: `null`) - Dispatches `HandlerStartingEvent`, `HandlerSuccessEvent`, `HandlerFailureEvent` around each handler.

### Request Example
```php
new HandleMessageMiddleware($handlersLocator, allowNoHandlers: false);
```

### Response
No return value.
```

--------------------------------

### Direct handler invocation with HandlersLocator

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handlers.md

Shows how to manually instantiate a HandlersLocator with a handler descriptor and invoke the handler for a given envelope. Useful for testing or exercising handlers directly without container wiring.

```php
use Symfony\Component\Messenger\Handler\HandlersLocator;
use Symfony\Component\Messenger\Handler\HandlerDescriptor;

$locator = new HandlersLocator([
    'App\Message\PlaceOrder' => [new HandlerDescriptor(static fn (PlaceOrder $m) => saveOrder($m))],
]);

foreach ($locator->getHandlers($envelope) as $descriptor) {
    $descriptor->getHandler()($envelope->getMessage());
}
```

--------------------------------

### InMemoryTransport class definition

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transports.md

Shows the public API of the in-memory transport. Use it for testing or same-process messaging. The constructor accepts an optional serializer and clock; methods like get(), ack(), and send() manage envelopes in memory.

```php
class InMemoryTransport implements TransportInterface, ListableReceiverInterface, MessageCountAwareInterface, ResetInterface
{
    public function __construct(
        private ?SerializerInterface $serializer = null,
        private ?ClockInterface $clock = null,
    ) {}
    public function get(/* int $fetchSize = 1 */): iterable
    public function ack(Envelope $envelope): void
    public function reject(Envelope $envelope): void
    public function getMessageCount(): int
    public function all(?int $limit = null): array
    public function find(mixed $id): ?Envelope
    public function send(Envelope $envelope): Envelope
    public function reset(): void
    public function getAcknowledged(): array
    public function getRejected(): array
    public function getSent(): array
}
```

--------------------------------

### InMemoryTransportFactory class definition

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transports.md

Factory for creating in-memory transports. Supports DSNs starting with 'in-memory://'. The 'serialize' query parameter (bool) enables serialization. Tracks created transports and resets them via reset(). Registered as 'messenger.transport.in_memory.factory' with 'kernel.reset' tag.

```php
class InMemoryTransportFactory implements TransportFactoryInterface, ResetInterface
{
    public function __construct(
        private readonly ?ClockInterface $clock = null,
    ) {}
    public function createTransport(string $dsn, array $options, SerializerInterface $serializer): TransportInterface
    public function supports(string $dsn, array $options): bool
    public function reset(): void
}
```

--------------------------------

### SingleMessageReceiver

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/receiver.md

Internal decorator that yields exactly one specific envelope on the first get() call and then behaves as empty. Used by the messenger:failed:retry command to retry a single failed message through a full Worker run. ack() and reject() delegate to the decorated receiver.

```php
class SingleMessageReceiver implements ReceiverInterface
{
    public function __construct(
        private ReceiverInterface $receiver,
        private Envelope $envelope,
    ) {}
    public function get(/* int $fetchSize = 1 */): iterable
    public function ack(Envelope $envelope): void   // delegates to the decorated receiver
    public function reject(Envelope $envelope): void // delegates to the decorated receiver
}
```

--------------------------------

### StackInterface next method

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Defines the contract for the middleware stack. Implementations must be cloneable, and each clone must unstack the stack independently, allowing sub-dispatches inside a handler to re-walk the remaining chain.

```php
interface StackInterface
{
    /**
     * Returns the next middleware to process a message.
     */
    public function next(): MiddlewareInterface;
}
```

--------------------------------

### SyncTransport class definition

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transports.md

Transport that handles messages synchronously. Constructor parameters: $messageBus (required), $retryStrategy, $failureSender, $eventDispatcher, $logger (all optional). Methods get(), ack(), reject() always throw InvalidArgumentException. send() stamps envelope with ReceivedStamp and dispatches; on failure, retries or sends to failure sender.

```php
class SyncTransport implements TransportInterface
{
    public function __construct(
        private MessageBusInterface $messageBus,
        private ?RetryStrategyInterface $retryStrategy = null,
        private ?SenderInterface $failureSender = null,
        private ?EventDispatcherInterface $eventDispatcher = null,
        private ?LoggerInterface $logger = null,
    ) {}
    public function get(/* int $fetchSize = 1 */): iterable
    public function ack(Envelope $envelope): void
    public function reject(Envelope $envelope): void
    public function send(Envelope $envelope): Envelope
}
```

--------------------------------

### Serializer

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/serializers.md

Documentation for the Serializer class, including constructor parameters and public methods.

```APIDOC
## Class: `Serializer`

### Description
Symfony Serializer component-based serializer for Messenger envelopes. Supports formats like JSON and XML. Produces `Content-Type` headers and encodes stamps into `X-Message-Stamp-<FQCN>` headers.

### Constructor
```php
public function __construct(
    ?SymfonySerializerInterface $serializer = null,
    private string $format = 'json',
    private array $context = [],
    private array $typeToClassMap = [],
)
```

### Constructor Parameters
- **$serializer** (?SymfonySerializerInterface) - Optional - Underlying serializer; defaults to a `create()`-built one (XmlEncoder + JsonEncoder, DateTimeNormalizer, ArrayDenormalizer, ObjectNormalizer, optional LockKeyNormalizer).
- **$format** (string) - Optional - Output format; `getMimeTypeForFormat()` maps json→`application/json`, xml→`application/xml`, yml/yaml→`application/yaml`, csv→`text/csv`, else `null` (no `Content-Type` header). Defaults to `'json'`.
- **$context** (array) - Optional - Serialization context; `MESSENGER_SERIALIZATION_CONTEXT => true` is forced in. Defaults to `[]`.
- **$typeToClassMap** (array<string, class-string>) - Optional - Serialized type name → class; flipped for encoding (last name listed wins). Defaults to `[]`.

### Methods

#### `create`
```php
public static function create(): self
```
Creates a new Serializer instance. Throws `Exception\LogicException` when `symfony/serializer` is not installed.

#### `decode`
```php
public function decode(array $encodedEnvelope): Envelope
```
Decodes an encoded envelope. Requires `body`, `headers`, and `headers.type`. Applies `SerializerStamp` context, maps type names, and wraps every failure into a `MessageDecodingFailedException` envelope (keeping stamps).

#### `getMessageType`
```php
public function getMessageType(array $encodedEnvelope): ?string
```
Returns the FQCN of the message carried by the encoded envelope. See `MessageTypeAwareSerializerInterface`.

#### `encode`
```php
public function encode(Envelope $envelope): array
```
Encodes an envelope. Reads a `SerializerStamp` context if present; re-emits the original body/headers for decode-failure envelopes; strips `NonSendableStampInterface` stamps; computes `type` from `AsMessage(serializedTypeName)` attributes or the message class; writes `X-Message-Stamp-<class>` headers.
```

--------------------------------

### Envelope immutability with with()

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/envelope.md

Demonstrates envelope immutability: with() returns a clone, leaving the original envelope unchanged.

```php
$original = Envelope::wrap($message);
$updated  = $original->with(new ReceivedStamp('amqp'));

// $original is untouched: $original->last(ReceivedStamp::class) === null
// $updated->last(ReceivedStamp::class)->getTransportName() === 'amqp'
```

--------------------------------

### TraceableMiddleware constructor

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Constructor for TraceableMiddleware. Records per-middleware timings on a Stopwatch for the debug profiler. The eventCategory defaults to 'messenger.middleware'.

```php
public function __construct(
    private Stopwatch $stopwatch,
    private string $busName,
    private string $eventCategory = 'messenger.middleware',
) {}
```

--------------------------------

### SyncMessageExecutionStrategy class constructor

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/execution.md

Default strategy that dispatches the envelope synchronously on the worker process. The constructor requires a MessageBusInterface and a closure that is invoked by the AckStamp closure wired through Worker::enqueueAck().

```php
final class SyncMessageExecutionStrategy implements MessageExecutionStrategyInterface
{
    public function __construct(
        private readonly MessageBusInterface $bus,
        private readonly \Closure $onAcknowledge,
    ) {}
}
```

--------------------------------

### StackMiddleware

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Concrete implementation of both MiddlewareInterface and StackInterface, providing a stack that can be used as a terminal middleware.

```APIDOC
## StackMiddleware::__construct

### Description
Constructs a new stack middleware instance.

### Method
__construct(iterable|MiddlewareInterface|null $middlewareIterator = null)

### Parameters
- **$middlewareIterator** (iterable|MiddlewareInterface|null) - Optional - An iterator, iterable, single middleware, or null. When a plain iterable is passed, it is converted into a lazily-rewound generator.
```

```APIDOC
## StackMiddleware::next

### Description
Returns the next middleware in the stack, or the tail when exhausted.

### Method
next(): MiddlewareInterface

### Parameters
None.

### Return Value
Returns the next MiddlewareInterface, or `$this` when the stack is exhausted.
```

```APIDOC
## StackMiddleware::handle

### Description
Terminal middleware that returns the envelope untouched.

### Method
handle(Envelope $envelope, StackInterface $stack): Envelope

### Parameters
- **$envelope** (Envelope) - Required - The envelope being dispatched.
- **$stack** (StackInterface) - Required - The rest of the middleware chain.

### Return Value
Returns the envelope unchanged.
```

--------------------------------

### Using AsMessage and AsMessageHandler attributes

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/attributes.md

Shows a message class with AsMessage attribute specifying transport and serialized type names, and a handler with AsMessageHandler attribute handling the message with priority.

```php
use Symfony\Component\Messenger\Attribute\AsMessage;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessage(transport: ['notifications'], serializedTypeName: 'events.user.registered', serializedTypeNameAliases: ['user_registered_v1'])]
final class UserRegistered
{
    public function __construct(public readonly string $email) {}
}

#[AsMessageHandler(handles: UserRegistered::class, priority: 10)]
class SendWelcomeEmailHandler
{
    public function __invoke(UserRegistered $message): void
    {
        // ...
    }
}
```

--------------------------------

### DispatchAfterCurrentBusMiddleware class skeleton

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/dispatch-after-current-bus-deduplicate-middleware.md

Class skeleton for DispatchAfterCurrentBusMiddleware, showing the queue and root-dispatch flag properties plus the handle() method signature. Use it to understand how the middleware tracks queued envelopes and whether the current dispatch is the root call.

```php
class DispatchAfterCurrentBusMiddleware implements MiddlewareInterface
{
    /**
     * @var QueuedEnvelope[] A queue of messages and next middleware
     */
    private array $queue = [];

    /**
     * @var bool this property is used to signal if we are inside a the first/root call to
     *           MessageBusInterface::dispatch() or if dispatch has been called inside a message handler
     */
    private bool $isRootDispatchCallRunning = false;

    public function handle(Envelope $envelope, StackInterface $stack): Envelope
}
```

--------------------------------

### Using HandleTrait in a command handler

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handle-trait.md

Shows the idiomatic usage of HandleTrait in an application service. The handle() method dispatches the message and returns the result of the single handler that handled it. Requires injecting a MessageBusInterface into the messageBus property.

```php
use Symfony\Component\Messenger\HandleTrait;

class CreateUserHandler
{
    use HandleTrait;

    public function __construct(MessageBusInterface $messageBus)
    {
        $this->messageBus = $messageBus;
    }

    public function createUser(string $email): User
    {
        // dispatch and expect EXACTLY ONE handler, returning its result
        return $this->handle(new CreateUser($email));
    }
}
```

--------------------------------

### Configure MultiplierRetryStrategy with constant delay

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/retry.md

Configures a MultiplierRetryStrategy with a constant 10s delay, at most 5 retries, and 20% jitter. Use isRetryable() to check whether a retry is allowed and getWaitingTime() to obtain the delay in milliseconds.

```php
use Symfony\Component\Messenger\Retry\MultiplierRetryStrategy;

// constant 10s delay between at most 5 retries, with 20% jitter
$strategy = new MultiplierRetryStrategy(
    maxRetries: 5,
    delayMilliseconds: 10000,
    multiplier: 1,
    maxDelayMilliseconds: 60000,
    jitter: 0.2,
);

if ($strategy->isRetryable($envelope, $lastError)) {
    $wait = $strategy->getWaitingTime($envelope, $lastError); // ms
}
```

--------------------------------

### LoggingMiddleware class definition

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Class definition for LoggingMiddleware with constructor and handle method. Measures processing time and memory, then logs outcome. On failure logs error('Unable to handle "{class}" message.') with duration_ms, memory_usage, and exception in context; on success with a SentStamp logs info('"{class}" message sent to transport.'); otherwise logs info('"{class}" message successfully handled.').

```php
class LoggingMiddleware implements MiddlewareInterface
{
    /**
     * @param ?(callable(): int) $memoryResolver
     */
    public function __construct(
        private LoggerInterface $logger,
        private ClockInterface $clock = new Clock(),
        ?callable $memoryResolver = null,
    ) {}
    public function handle(Envelope $envelope, StackInterface $stack): Envelope
}
```

--------------------------------

### SendMessageMiddleware class definition

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/send-message-middleware.md

The class implements MiddlewareInterface and uses LoggerAwareTrait. The constructor accepts a SendersLocatorInterface, an optional EventDispatcherInterface, and an optional bool for allowNoSenders. The handle method takes an Envelope and StackInterface and returns an Envelope.

```php
class SendMessageMiddleware implements MiddlewareInterface
{
    use LoggerAwareTrait;

    public function __construct(
        private SendersLocatorInterface $sendersLocator,
        private ?EventDispatcherInterface $eventDispatcher = null,
        private bool $allowNoSenders = true,
    ) {}
    public function handle(Envelope $envelope, StackInterface $stack): Envelope
}
```

--------------------------------

### HandleMessageMiddleware class definition

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handle-message-middleware.md

The HandleMessageMiddleware class implements MiddlewareInterface. Its constructor accepts a HandlersLocatorInterface, an optional bool to allow no handlers, an optional ClockInterface, and an optional EventDispatcherInterface. The handle method processes an Envelope with a StackInterface and returns an Envelope.

```php
class HandleMessageMiddleware implements MiddlewareInterface
{
    use LoggerAwareTrait;

    public function __construct(
        private HandlersLocatorInterface $handlersLocator,
        private bool $allowNoHandlers = false,
        private ?ClockInterface $clock = null,
        private ?EventDispatcherInterface $dispatcher = null,
    ) {}
    public function handle(Envelope $envelope, StackInterface $stack): Envelope
}
```

--------------------------------

### BatchHandlerTrait: buffering and flush policy

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handlers.md

Provides the buffering and policy logic for batch handlers. The using class must implement the abstract private process() method. Override getBatchSize() or getIdleTimeout() to change the default batch size (10) or idle timeout (1 second).

```php
trait BatchHandlerTrait
{
    public function flush(bool $force): void
    // private handle(object $message, ?Acknowledger $ack): mixed
    // private shouldFlush(): bool
    abstract private function process(array $jobs): void;
    private function getBatchSize(): int            // returns 10
    private function getIdleTimeout(): ?int          // returns 1 (second)
}
```

--------------------------------

### TransportFactory class implementation

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transport.md

Defines the TransportFactory class with a constructor accepting an iterable of factories, and methods createTransport and supports. The createTransport method throws an InvalidArgumentException when no factory supports the DSN, with a message that sanitizes credentials and suggests a package based on the scheme.

```php
/**
 * @implements TransportFactoryInterface<TransportInterface>
 */
class TransportFactory implements TransportFactoryInterface
{
    /**
     * @param iterable<mixed, TransportFactoryInterface> $factories
     */
    public function __construct(
        private iterable $factories,
    ) {}
    public function createTransport(#[[SensitiveParameter] string $dsn, array $options, SerializerInterface $serializer): TransportInterface
    public function supports(#[[SensitiveParameter] string $dsn, array $options): bool
}
```

--------------------------------

### StackInterface::next

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Contract for the middleware stack, providing access to the next middleware in the chain.

```APIDOC
## StackInterface::next

### Description
Returns the next middleware to process a message. Implementations must be cloneable, and each clone must unstack the stack independently.

### Method
next(): MiddlewareInterface

### Parameters
None.

### Return Value
Returns the next MiddlewareInterface instance.
```

--------------------------------

### BatchHandlerInterface with flush(bool $force)

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handlers.md

Interface for batch handlers. Implementations are invocable services taking (object $message, ?Acknowledger $ack = null); with $ack non-null they buffer and return pending count, with null they handle synchronously. flush(bool $force) completes buffered jobs; HandleMessageMiddleware wraps calls with an internal Acknowledger when $ack is null.

```php
interface BatchHandlerInterface
{
    /**
     * @param Acknowledger|null $ack The function to call to ack/nack the $message.
     *                               The message should be handled synchronously when null.
     *
     * @return mixed The number of pending messages in the batch if $ack is not null,
     *               the result from handling the message otherwise
     */
    // public function __invoke(object $message, ?Acknowledger $ack = null): mixed;

    /**
     * Flushes any pending buffers.
     *
     * @param bool $force Whether flushing is required; it can be skipped if not
     */
    public function flush(bool $force): void;
}
```

--------------------------------

### ListableReceiverInterface

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/receiver.md

Defines all() and find() methods for transports that can introspect queued messages. Implementations must add a TransportMessageIdStamp to returned envelopes.

```php
interface ListableReceiverInterface extends ReceiverInterface
{
    /**
     * Returns all the messages (up to the limit) in this receiver.
     * Messages should be given the same stamps as when using ReceiverInterface::get().
     *
     * @return iterable<Envelope>
     */
    public function all(?int $limit = null): iterable;

    /**
     * Returns the Envelope by id or none.
     * Message should be given the same stamps as when using ReceiverInterface::get().
     */
    public function find(mixed $id): ?Envelope;
}
```

--------------------------------

### InMemoryTransport

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transports.md

Documentation for the InMemoryTransport class, including constructor parameters and all public methods.

```APIDOC
## InMemoryTransport

### Description
In-memory transport for testing and same-process messaging. Implements `TransportInterface`, `ListableReceiverInterface`, `MessageCountAwareInterface`, and `ResetInterface`.

### Constructor

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$serializer` | `?SerializerInterface` | `null` | When set, every stored/queued envelope is encoded/decoded through it (round-trip fidelity) |
| `$clock` | `?ClockInterface` | `null` | Clock for `DelayStamp` scheduling and `get()` availability; defaults to `new \DateTimeImmutable()` zones |

### Methods

#### `get(int $fetchSize = 1): iterable`

Yields envelopes whose `DelayStamp` delay has elapsed (availableAt), decoded.

#### `ack(Envelope $envelope): void`

Moves the encoded envelope into `acknowledged` list and removes it from the queue. Throws `Exception\LogicException('No TransportMessageIdStamp found on the Envelope.')` when the envelope has no `TransportMessageIdStamp`.

#### `reject(Envelope $envelope): void`

Moves the encoded envelope into `rejected` list and removes it from the queue. Throws `Exception\LogicException('No TransportMessageIdStamp found on the Envelope.')` when the envelope has no `TransportMessageIdStamp`.

#### `getMessageCount(): int`

Returns the number of queued messages.

#### `all(?int $limit = null): array`

Returns queued envelopes in order, including delayed ones.

#### `find(mixed $id): ?Envelope`

Returns the envelope by id (int/string), or `null` if not found.

#### `send(Envelope $envelope): Envelope`

Assigns `TransportMessageIdStamp` (incrementing int), stores it (encoded), schedules `availableAt` when a `DelayStamp` is present. Returns the envelope with the id stamp.

#### `reset(): void`

Empties sent/queue/rejected/acknowledged lists.

#### `getAcknowledged(): array`

Returns the acknowledged envelopes (decoded).

#### `getRejected(): array`

Returns the rejected envelopes (decoded).

#### `getSent(): array`

Returns the sent envelopes (decoded).
```

--------------------------------

### Acknowledger::__construct

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/handlers.md

Creates a new Acknowledger instance. The clock defaults to Clock::get().

```APIDOC
## Acknowledger::__construct

### Description
Creates a new Acknowledger instance. The `$handlerClass` is used in error messages to name the offending handler. The `$clock` defaults to `Clock::get()`.

### Method
`__construct(string $handlerClass, ?\Closure $ack = null, ?ClockInterface $clock = null)`

### Parameters
- **$handlerClass** (string) - Required - The class name of the batch handler.
- **$ack** (\Closure|null) - Optional - The closure to call for ack/nack. Signature: `function(\Throwable|null $error, mixed $result): void`.
- **$clock** (ClockInterface|null) - Optional - The clock to use. Defaults to `Clock::get()`.

### Return
None (constructor).

### Source
`Handler/Acknowledger.php:32`
```

--------------------------------

### MessageExecutionStrategyInterface

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/execution.md

Defines the contract for execution strategies. The $onHandled callback must receive the bool $acked by reference; passing a literal silently breaks batch acking. flush() accepts true/false to force/skip or a float as max age in seconds.

```php
interface MessageExecutionStrategyInterface
{
    /**
     * @param callable(Envelope, string, bool &$acked, ?\Throwable): void $onHandled
     */
    public function execute(Envelope $envelope, string $transportName, callable $onHandled): void;

    public function shouldPauseConsumption(): bool;

    /**
     * @param callable(Envelope, string, bool &$acked, ?\Throwable): void $onHandled
     */
    public function wait(callable $onHandled): bool;

    /**
     * @param callable(Envelope, string, bool &$acked, ?\Throwable): void $onHandled
     */
    public function flush(callable $onHandled, bool|float $force = false): bool;

    public function shutdown(): void;
}
```

--------------------------------

### SigningSerializer class signature

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/serializers.md

Shows the constructor and public methods of the final SigningSerializer. The constructor requires an inner serializer, a sensitive signing key, and a list of signed message types; the algorithm defaults to 'sha256'. Use this to understand how to configure HMAC signing for encoded envelopes.

```php
final class SigningSerializer implements SerializerInterface
{
    /**
     * @param list<class-string> $signedMessageTypes
     */
    public function __construct(
        private SerializerInterface $inner,
        #\[SensitiveParameter\] private string|\Stringable $signingKey,
        private array $signedMessageTypes,
        private string $algorithm = 'sha256',
    ) {}
    public function encode(Envelope $envelope): array
    public function decode(array $encodedEnvelope): Envelope
}
```

--------------------------------

### AddDefaultStampsMiddleware handle method

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/middleware.md

Adds default stamps to the envelope if the message implements Message\DefaultStampsProviderInterface. Stamps returned by getDefaultStamps() are added unless the envelope already carries a stamp of the same class.

```php
public function handle(Envelope $envelope, StackInterface $stack): Envelope
```

--------------------------------

### SyncTransport usage for command/query testing

Source: https://github.com/symfony/messenger/blob/8.2/_autodocs/api-reference/transports.md

Creates a synchronous transport for command/query style testing. The send() call handles the message synchronously. If retries are exhausted and no failureSender is provided, the original exception is thrown and can be caught.

```php
use Symfony\Component\Messenger\Transport\Sync\SyncTransport;

$sync = new SyncTransport($bus, retryStrategy: $retry, failureSender: $failureSender);
try {
    $result = $sync->send($envelope); // synchronously handled
} catch (\Throwable $e) {
    // retries exhausted and no failureSender: the original exception surfaces
}
```
Tokens:
Raw