Add stamps to handle trait

alexander-schranz · OskarStark · alexander-schranz · commit 2f044ea3dd7d · 2024-12-13T14:41:30.000+01:00
Co-authored-by: Oskar Stark &lt;oskarstark@googlemail.com&gt;
diff --git a/src/Symfony/Component/Messenger/CHANGELOG.md b/src/Symfony/Component/Messenger/CHANGELOG.md
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.3
+---
+
+ * Add `$stamps = []` parameter to `HandleTrait`
+
 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 middlewares behaviors
      */
-    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);
 
@@ -48,7 +50,7 @@ private function handle(object $message): mixed
         if (\count($handledStamps) > 1) {
             $handlers = implode(', ', array_map(fn (HandledStamp $stamp): string => \sprintf('"%s"', $stamp->getHandlerName()), $handledStamps));
 
-            throw new LogicException(\sprintf('Message of type "%s" was handled multiple times. Only one handler is expected when using "%s::%s()", got %d: %s.', get_debug_type($envelope->getMessage()), static::class, __FUNCTION__, \count($handledStamps), $handlers));
+            throw new LogicException(\sprintf('Message of type "%s" was handled multiple times. Only one handler is expected when using "%s::%s()", got %d: "%s".', get_debug_type($envelope->getMessage()), static::class, __FUNCTION__, \count($handledStamps), $handlers));
         }
 
         return $handledStamps[0]->getResult();
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 middlewares behaviors
      *
      * @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 middlewares behaviors`
`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`	`}`