[Messenger] HandlerArgumentsStamp

Author: enumag

messenger.rst

@@ -926,7 +926,7 @@ to retry them:
 
     # see all messages in the failure transport with a default limit of 50
     $ php bin/console messenger:failed:show
-    
+
     # see the 10 first messages
     $ php bin/console messenger:failed:show --max=10
 
@@ -2263,6 +2263,62 @@ of the process. For each, the event class is the event name:
 * :class:`Symfony\\Component\\Messenger\\Event\\WorkerRunningEvent`
 * :class:`Symfony\\Component\\Messenger\\Event\\WorkerStoppedEvent`
 
+Additional Handler Arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's possible to have messenger pass additional data to the message handler using the
+:class:`Symfony\\Component\\Messenger\\Stamp\\HandlerArgumentsStamp`. Add this stamp to
+the envelope in a middleware and fill it with any additional data you want to have
+available in the handler.
+
+    // src/Library/Messenger/AdditionalArgumentMiddleware.php
+    namespace App\Library\Messenger;
+
+    use Symfony\Component\Messenger\Envelope;
+    use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
+    use Symfony\Component\Messenger\Middleware\StackInterface;
+    use Symfony\Component\Messenger\Stamp\HandlerArgumentsStamp;
+
+    class AdditionalArgumentMiddleware implements MiddlewareInterface
+    {
+        public function handle(Envelope $envelope, StackInterface $stack): Envelope
+        {
+            $envelope = $envelope->with(
+                new HandlerArgumentsStamp(
+                    [
+                        $this->resolveAdditionalArgument($envelope->getMessage()),
+                    ],
+                ),
+            )
+
+            return $stack->next()->handle($envelope, $stack);
+        }
+
+        private function resolveAdditionalArgument(object $message): mixed
+        {
+            // ...
+        }
+    }
+
+Then your handler will look like this:
+
+    // src/MessageHandler/SmsNotificationHandler.php
+    namespace App\MessageHandler;
+
+    use App\Message\SmsNotification;
+
+    class SmsNotificationHandler
+    {
+        public function __invoke(SmsNotification $message, mixed $additionalArgument)
+        {
+            // ...
+        }
+    }
+
+.. versionadded:: 6.2
+
+    The HandlerArgumentsStamp was introduced in Symfony 6.2.
+
 Multiple Buses, Command & Event Buses
 -------------------------------------