Important: #107032 - AsMessageHandler "fromTransport" property is now honoured
See forge#107032
Description
Symfony Messenger's
\Symfony\
attribute provides a
from 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:).
So far TYPO3 collected the attribute but dropped the
from 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\, 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
{
// ...
}
}
Resolution rules:
- A handler without
fromkeeps running for every matching message, regardless of the receiving transport (unchanged behaviour).Transport - A handler with
fromonly runs when the message carries aTransport Receivedfor one of the bound transports. A message dispatched and handled synchronously (noStamp Received, i.e. not received from a worker) is not affected by the restriction and still reaches the handler.Stamp
Binding a handler to multiple transports
A handler may be bound to more than one receiving transport. As the Symfony
As attribute only accepts a single transport name per
attribute, several transports are expressed by repeating the attribute (it is
\Attribute::):
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
{
// ...
}
}
When a handler is registered via a service tag instead of the attribute, the
from 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' ]
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
from 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
from property from such a handler to restore the previous
"handle everything" behaviour.
Note
This controls the consumer side (which handler runs for a received
message). The sender side - which transport a message is routed to when
dispatched - is a separate concern: a wildcard route (a namespace wildcard
or the global
'*'
) now acts as a fallback and no longer fans out in
addition to a matching specific route (see forge#101699 and
forge#110223). Combining fallback routing on the sender side with a
from-bound handler on the consumer side is what enables a
fully separated asynchronous send/receive setup.
Providing this change on older TYPO3 versions
The fix spans two core classes:
\TYPO3\stores the transport binding and builds one handler descriptor per receiving transport, andCMS\ Core\ Messenger\ Handlers Locator Factory \TYPO3\reads theCMS\ Core\ Dependency Injection\ Message Handler Pass fromtag option and carries it into that factory.Transport
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.. As the
from 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/.
Backport the change via a Composer patch
Apply the change to typo3/ 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"
}
}
}
}
The patch file should contain the diff of both
typo3/ and
typo3/,
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
Handlers into the extension, for example as
\My, 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
Because
Message resolves the factory definition by the core
class name (and the alias resolves to the extension definition), the compiler
pass adds its
add calls to the extension implementation.
Note
Due to the monorepo to composer package splitting a patch requires adoption
of the paths and stripping out changes in Tests/ folders.
See Applying Core patches for further details on how to create and apply Composer patches for TYPO3.