Important: #107032 - AsMessageHandler "fromTransport" property is now honoured 

See forge#107032

Description 

Symfony Messenger's \Symfony\Component\Messenger\Attribute\AsMessageHandler attribute provides a fromTransport property to bind a message handler to a single receiving transport: the handler is then only executed for messages that were received from that transport by a worker ( typo3 messenger:consume <transport> ).

So far TYPO3 collected the attribute but dropped the fromTransport value while building the handler map, so the property had no effect and a handler declaring it was executed for the message regardless of the transport the message was received from. This made a proper asynchronous send/receive setup - where a message is consumed from a dedicated transport and only the matching handler runs - impossible to express.

The value is now passed through to the handler descriptor and evaluated against the envelope's \Symfony\Component\Messenger\Stamp\ReceivedStamp , matching the upstream Symfony behaviour:

use Symfony\Component\Messenger\Attribute\AsMessageHandler;

// Only runs for MyMessage instances received from the "async" transport.
#[AsMessageHandler(fromTransport: 'async')]
final readonly class MyAsyncHandler
{
    public function __invoke(MyMessage $message): void
    {
        // ...
    }
}
Copied!

Resolution rules:

  • A handler without fromTransport keeps running for every matching message, regardless of the receiving transport (unchanged behaviour).
  • A handler with fromTransport only runs when the message carries a ReceivedStamp for one of the bound transports. A message dispatched and handled synchronously (no ReceivedStamp , i.e. not received from a worker) is not affected by the restriction and still reaches the handler.

Binding a handler to multiple transports 

A handler may be bound to more than one receiving transport. As the Symfony AsMessageHandler attribute only accepts a single transport name per attribute, several transports are expressed by repeating the attribute (it is \Attribute::IS_REPEATABLE ):

use Symfony\Component\Messenger\Attribute\AsMessageHandler;

// Runs for MyMessage received from the "async" or the "priority" transport.
#[AsMessageHandler(fromTransport: 'async')]
#[AsMessageHandler(fromTransport: 'priority')]
final readonly class MyAsyncHandler
{
    public function __invoke(MyMessage $message): void
    {
        // ...
    }
}
Copied!

When a handler is registered via a service tag instead of the attribute, the fromTransport tag option additionally accepts a list of transport names ( string , list<string> or null ):

services:
  MyVendor\MyExtension\Messenger\MyAsyncHandler:
    tags:
      - name: 'messenger.message_handler'
        fromTransport: [ 'async', 'priority' ]
Copied!

Duplicate and empty transport names are ignored, and the handler runs at most once per received message even when several bindings match.

Impact 

Installations that already annotated a handler with fromTransport and (knowingly or not) relied on the value being ignored will see that handler no longer run for messages received from a different transport. Remove the fromTransport property from such a handler to restore the previous "handle everything" behaviour.

Providing this change on older TYPO3 versions 

The fix spans two core classes:

  • \TYPO3\CMS\Core\Messenger\HandlersLocatorFactory stores the transport binding and builds one handler descriptor per receiving transport, and
  • \TYPO3\CMS\Core\DependencyInjection\MessageHandlerPass reads the fromTransport tag option and carries it into that factory.

The factory is a regular service and can be swapped through Configuration/Services.yaml. The pass, however, is a Symfony compiler pass registered in core's Configuration/Services.php - it is not a service and cannot be replaced through Services.yaml. As the fromTransport value is already dropped inside that pass on an older core, replacing only the factory is not sufficient: the value never reaches it.

Because a second, corrected compiler pass registered from an extension would run in addition to the core one (re-adding the handler unbound and defeating the restriction), a local extension can only provide the corrected factory, not the corrected pass. A complete backport therefore requires a Composer patch that adjusts both classes in typo3/cms-core.

Backport the change via a Composer patch 

Apply the change to typo3/cms-core using a Composer patch tool such as cweagans/composer-patches:

{
    "require": {
        "cweagans/composer-patches": "^1.7"
    },
    "extra": {
        "patches": {
            "typo3/cms-core": {
                "Honour AsMessageHandler fromTransport": "patches/messenger-from-transport.patch"
            }
        }
    }
}
Copied!

The patch file should contain the diff of both typo3/sysext/core/Classes/Messenger/HandlersLocatorFactory.php and typo3/sysext/core/Classes/DependencyInjection/MessageHandlerPass.php, and is applied automatically on composer install .

Optionally replace the factory in a local extension 

If the corrected pass is provided by a Composer patch, the corrected factory may instead live in a local extension. Copy the current HandlersLocatorFactory into the extension, for example as \MyVendor\MyExtension\Messenger\HandlersLocatorFactory , and re-point the core service to it in the extension's Configuration/Services.yaml:

services:
  MyVendor\MyExtension\Messenger\HandlersLocatorFactory: ~

  # replace the core factory the messenger handlers locator is built from
  TYPO3\CMS\Core\Messenger\HandlersLocatorFactory:
    alias: MyVendor\MyExtension\Messenger\HandlersLocatorFactory
Copied!

Because MessageHandlerPass resolves the factory definition by the core class name (and the alias resolves to the extension definition), the compiler pass adds its addHandler() calls to the extension implementation.