symfony · chalasr · Mar 29, 2025 · Dec 13, 2024
diff --git a/src/Symfony/Component/Messenger/CHANGELOG.md b/src/Symfony/Component/Messenger/CHANGELOG.md
@@ -8,6 +8,7 @@ CHANGELOG
  * Add `SentForRetryStamp` that identifies whether a failed message was sent for retry
  * Add `Symfony\Component\Messenger\Middleware\DeduplicateMiddleware` and `Symfony\Component\Messenger\Stamp\DeduplicateStamp`
  * Add `--class-filter` option to the `messenger:failed:remove` command
+ * Add `$stamps` parameter to `HandleTrait::handle`
 
 7.2
 ---

diff --git a/src/Symfony/Component/Messenger/HandleTrait.php b/src/Symfony/Component/Messenger/HandleTrait.php
@@ -13,6 +13,7 @@
 
 use Symfony\Component\Messenger\Exception\LogicException;
 use Symfony\Component\Messenger\Stamp\HandledStamp;
+use Symfony\Component\Messenger\Stamp\StampInterface;
 
 /**
  * Leverages a message bus to expect a single, synchronous message handling and return its result.
@@ -29,15 +30,16 @@ trait HandleTrait
      * This behavior is useful for both synchronous command & query buses,
      * the last one usually returning the handler result.
      *
-     * @param object|Envelope $message The message or the message pre-wrapped in an envelope
+     * @param object|Envelope  $message The message or the message pre-wrapped in an envelope
+     * @param StampInterface[] $stamps  Stamps to be set on the Envelope which are used to control middleware behavior
      */
-    private function handle(object $message): mixed
+    private function handle(object $message, array $stamps = []): mixed
     {
         if (!isset($this->messageBus)) {
             throw new LogicException(\sprintf('You must provide a "%s" instance in the "%s::$messageBus" property, but that property has not been initialized yet.', MessageBusInterface::class, static::class));
         }
 
-        $envelope = $this->messageBus->dispatch($message);
+        $envelope = $this->messageBus->dispatch($message, $stamps);
         /** @var HandledStamp[] $handledStamps */
         $handledStamps = $envelope->all(HandledStamp::class);
 

diff --git a/src/Symfony/Component/Messenger/MessageBusInterface.php b/src/Symfony/Component/Messenger/MessageBusInterface.php
@@ -23,7 +23,7 @@ interface MessageBusInterface
      * Dispatches the given message.
      *
      * @param object|Envelope  $message The message or the message pre-wrapped in an envelope
-     * @param StampInterface[] $stamps
+     * @param StampInterface[] $stamps  Stamps set on the Envelope which are used to control middleware behavior
      *
      * @throws ExceptionInterface
      */

diff --git a/src/Symfony/Component/Messenger/Tests/HandleTraitTest.php b/src/Symfony/Component/Messenger/Tests/HandleTraitTest.php
@@ -18,6 +18,7 @@
 use Symfony\Component\Messenger\MessageBus;
 use Symfony\Component\Messenger\MessageBusInterface;
 use Symfony\Component\Messenger\Stamp\HandledStamp;
+use Symfony\Component\Messenger\Stamp\StampInterface;
 use Symfony\Component\Messenger\Tests\Fixtures\DummyMessage;
 
 class HandleTraitTest extends TestCase
@@ -56,6 +57,20 @@ public function testHandleAcceptsEnvelopes()
         $this->assertSame('result', $queryBus->query($envelope));
     }
 
+    public function testHandleWithStamps()
+    {
+        $bus = $this->createMock(MessageBus::class);
+        $queryBus = new TestQueryBus($bus);
+        $stamp = $this->createMock(StampInterface::class);
+
+        $query = new DummyMessage('Hello');
+        $bus->expects($this->once())->method('dispatch')->with($query, [$stamp])->willReturn(
+            new Envelope($query, [new HandledStamp('result', 'DummyHandler::__invoke')])
+        );
+
+        $queryBus->query($query, [$stamp]);
+    }
+
     public function testHandleThrowsOnNoHandledStamp()
     {
         $this->expectException(LogicException::class);
@@ -96,8 +111,8 @@ public function __construct(?MessageBusInterface $messageBus)
         }
     }
 
-    public function query($query): string
+    public function query($query, array $stamps = []): string
     {
-        return $this->handle($query);
+        return $this->handle($query, $stamps);
     }
 }