diff --git a/messenger.rst b/messenger.rst index fdaa405371a..2e496a8ecf7 100644 --- a/messenger.rst +++ b/messenger.rst @@ -821,6 +821,116 @@ If the message fails again, it will be re-sent back to the failure transport due to the normal :ref:`retry rules `. Once the max retry has been hit, the message will be discarded permanently. +Multiple failed transports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes is not enough having one single global ``failed transport`` configured because +some messages are more important than others: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/messenger.yaml + framework: + messenger: + # after retrying, messages will be sent to the "failed" transport + # by default if no "failed_transport" is configured inside a transport + failure_transport: failed + + transports: + async_priority_high: + dsn: '%env(MESSENGER_TRANSPORT_DSN)%' + failed_transport: failed + + # since no failed transport is configured, the one used will be + # the global "failed_transport" set + async_priority_low: + dsn: 'doctrine://default?queue_name=async_priority_low' + + failed: 'doctrine://default?queue_name=failed' + failed_other: 'doctrine://default?queue_name=failed_other' + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + .. code-block:: php + + // config/packages/messenger.php + $container->loadFromExtension('framework', [ + 'messenger' => [ + // after retrying, messages will be sent to the "failed" transport + // by default if no "failed_transport" is configured inside a transport + 'failure_transport' => 'failed', + + 'transports' => [ + 'async_priority_high' => [ + 'dsn' => '%env(MESSENGER_TRANSPORT_DSN)%', + 'failed_transport' => 'failed' + ], + // since no failed transport is configured, the one used will be + // the global failed_transport set + 'async_priority_low' => [ + 'dsn' => 'doctrine://default?queue_name=async_priority_low', + ], + 'failed' => [ + 'dsn' => 'doctrine://default?queue_name=failed', + ], + ], + ], + ]); + +The transport with a ``failed_transport`` configuration defined, will override the global ``failed_transport``. + +If there is no ``failed_transport`` defined globally or on the transport level, the messages +will be discarded after the number of retries. + +The failed commands have an optional argument to specify the ``failed_transport`` configured at the transport level: + +.. code-block:: terminal + + # see all messages in the failure transport + $ php bin/console messenger:failed:show --failure-transport={failure_transport} + + # see details about a specific failure + $ php bin/console messenger:failed:show 20 --failure-transport={failure_transport} -vv + + # view and retry messages one-by-one + $ php bin/console messenger:failed:retry -vv + + # retry specific messages + $ php bin/console messenger:failed:retry 20 30 --failure-transport={failure_transport} --force + + # remove a message without retrying it + $ php bin/console messenger:failed:remove 20 --failure-transport={failure_transport} + + # remove messages without retrying them and show each message before removing it + $ php bin/console messenger:failed:remove 20 30 --failure-transport={failure_transport} --show-messages + .. _messenger-transports-config: Transport Configuration