minor #18852 [Messenger] Mention RedispatchMessage and RedispatchMessageHandler (alexandre-daubois)

javiereguiluz · javiereguiluz · commit 71476e4cfc31 · 2023-09-11T17:56:49.000+02:00
This PR was merged into the 6.4 branch. Discussion ---------- [Messenger] Mention `RedispatchMessage` and `RedispatchMessageHandler` Fix #18098 Commits ------- 55d687e [Messenger] Mention `RedispatchMessage` and `RedispatchMessageHandler`
diff --git a/messenger.rst b/messenger.rst
@@ -2738,6 +2738,54 @@ Messenger gives you a single message bus service by default. But, you can config
 as many as you want, creating "command", "query" or "event" buses and controlling
 their middleware. See :doc:`/messenger/multiple_buses`.
 
+Redispatching a Message
+-----------------------
+
+It may occur that you dispatch a message and for some reason, wants to
+redispatch it through the same transport with the same envelope. To do so, you
+can create a new
+:class:`Symfony\\Component\\Messenger\\Message\\RedispatchMessage` and dispatch
+it through your bus. Let's do this with the ``SmsNotification`` seen earlier::
+
+    // src/MessageHandler/SmsNotificationHandler.php
+    namespace App\MessageHandler;
+
+    use App\Message\SmsNotification;
+    use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+    use Symfony\Component\Messenger\MessageBusInterface;
+    use Symfony\Component\Messenger\Message\RedispatchMessage;
+
+    #[AsMessageHandler]
+    class SmsNotificationHandler
+    {
+        public function __construct(private MessageBusInterface $bus)
+        {
+        }
+
+        public function __invoke(SmsNotification $message): void
+        {
+            // do something with the message
+            // then redispatch it based on your own logic
+
+            if ($needsRedispatch) {
+                $this->bus->dispatch(new RedispatchMessage($message));
+            }
+        }
+    }
+
+The built-in
+:class:`Symfony\\Component\\Messenger\\Handler\\RedispatchMessageHandler` will
+take care of this message and redispatch it through the same bus it's been
+dispatched at first. You can also use the second argument of the
+``RedispatchMessage`` constructor to provide transports to use when
+redispatching the message.
+
+.. versionadded:: 6.3
+
+    The :class:`Symfony\\Component\\Messenger\\Message\\RedispatchMessage`
+    and :class:`Symfony\\Component\\Messenger\\Handler\\RedispatchMessageHandler`
+    classes were introduced in Symfony 6.3.
+
 Learn more
 ----------
 
