feature #42124 [Messenger] Add $stamps parameter to HandleTrait::handle (alexander-schranz)

chalasr · chalasr · commit c6baf1b99ef5 · 2025-03-29T15:45:45.000+01:00
This PR was merged into the 7.3 branch. Discussion ---------- [Messenger] Add `$stamps` parameter to `HandleTrait::handle` | Q | A | ------------- | --- | Branch? | 7.3 | Bug fix? | no | New feature? | yes | Deprecations? | no | Tickets | -- | License | MIT | Doc PR | TODO Like the `MessageBusInterface::dispatch` it would be great to use stamps. We are using example a custom middleware to control if a flush should be done. ```php $this->handle(new CreateUserMessage($data), [new DoctrineFlushStamp()]); ``` Also a custom middleware for locking: ```php $this->handle(new OurMessage(), [new LockStamp('lock-key', 300.0, true)])); ``` Commits ------- 1742f67 Add stamps to handle trait
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);
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,7 @@ interface MessageBusInterface`
`23`	`23`	`* Dispatches the given message.`
`24`	`24`	`*`
`25`	`25`	`* @param object\|Envelope $message The message or the message pre-wrapped in an envelope`
`26`		`- * @param StampInterface[] $stamps`
	`26`	`+ * @param StampInterface[] $stamps Stamps set on the Envelope which are used to control middleware behavior`
`27`	`27`	`*`
`28`	`28`	`* @throws ExceptionInterface`
`29`	`29`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@`
`18`	`18`	`use Symfony\Component\Messenger\MessageBus;`
`19`	`19`	`use Symfony\Component\Messenger\MessageBusInterface;`
`20`	`20`	`use Symfony\Component\Messenger\Stamp\HandledStamp;`
	`21`	`+use Symfony\Component\Messenger\Stamp\StampInterface;`
`21`	`22`	`use Symfony\Component\Messenger\Tests\Fixtures\DummyMessage;`
`22`	`23`
`23`	`24`	`class HandleTraitTest extends TestCase`
`@@ -56,6 +57,20 @@ public function testHandleAcceptsEnvelopes()`
`56`	`57`	`$this->assertSame('result', $queryBus->query($envelope));`
`57`	`58`	`}`
`58`	`59`
	`60`	`+ public function testHandleWithStamps()`
	`61`	`+ {`
	`62`	`+ $bus = $this->createMock(MessageBus::class);`
	`63`	`+ $queryBus = new TestQueryBus($bus);`
	`64`	`+ $stamp = $this->createMock(StampInterface::class);`
	`65`	`+`
	`66`	`+ $query = new DummyMessage('Hello');`
	`67`	`+ $bus->expects($this->once())->method('dispatch')->with($query, [$stamp])->willReturn(`
	`68`	`+ new Envelope($query, [new HandledStamp('result', 'DummyHandler::__invoke')])`
	`69`	`+ );`
	`70`	`+`
	`71`	`+ $queryBus->query($query, [$stamp]);`
	`72`	`+ }`
	`73`	`+`
`59`	`74`	`public function testHandleThrowsOnNoHandledStamp()`
`60`	`75`	`{`
`61`	`76`	`$this->expectException(LogicException::class);`
`@@ -96,8 +111,8 @@ public function __construct(?MessageBusInterface $messageBus)`
`96`	`111`	`}`
`97`	`112`	`}`
`98`	`113`
`99`		`- public function query($query): string`
	`114`	`+ public function query($query, array $stamps = []): string`
`100`	`115`	`{`
`101`		`- return $this->handle($query);`
	`116`	`+ return $this->handle($query, $stamps);`
`102`	`117`	`}`
`103`	`118`	`}`