symfony · sroze · Oct 26, 2018 · Oct 25, 2018
diff --git a/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php b/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php
@@ -27,6 +27,7 @@
 use Symfony\Component\HttpFoundation\StreamedResponse;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 use Symfony\Component\HttpKernel\HttpKernelInterface;
+use Symfony\Component\Messenger\Envelope;
 use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 use Symfony\Component\Security\Core\Exception\AccessDeniedException;
 use Symfony\Component\Security\Csrf\CsrfToken;
@@ -394,7 +395,7 @@ protected function isCsrfTokenValid(string $id, ?string $token): bool
      *
      * @final
      */
-    protected function dispatchMessage($message)
+    protected function dispatchMessage($message): Envelope
     {
         if (!$this->container->has('message_bus')) {
             throw new \LogicException('The message bus is not enabled in your application. Try running "composer require symfony/messenger".');

diff --git a/src/Symfony/Component/Messenger/CHANGELOG.md b/src/Symfony/Component/Messenger/CHANGELOG.md
@@ -6,7 +6,7 @@ CHANGELOG
 
  * The component is not experimental anymore
  * All the changes below are BC BREAKS
- * `MessageBusInterface::dispatch()` and `MiddlewareInterface::handle()` now return `void`
+ * `MessageBusInterface::dispatch()`, `MiddlewareInterface::handle()` and `SenderInterface::send()` return `Envelope`
  * `MiddlewareInterface::handle()` now require an `Envelope` as first argument and a `StackInterface` as second
  * `EnvelopeAwareInterface` has been removed
  * The signature of `Amqp*` classes changed to take a `Connection` as a first argument and an optional
@@ -31,7 +31,6 @@ CHANGELOG
  * `AbstractHandlerLocator` is now internal
  * `HandlerLocatorInterface::resolve()` has been replaced by `getHandler(Envelope $envelope): ?callable` and shouldn't throw when no handlers are found
  * `SenderLocatorInterface::getSenderForMessage()` has been replaced by `getSender(Envelope $envelope)`
- * `SenderInterface::send()` returns `void`
  * Classes in the `Middleware\Enhancers` sub-namespace have been moved to the `Middleware` one
  * Classes in the `Asynchronous\Routing` sub-namespace have been moved to the `Transport\Sender\Locator` sub-namespace
  * The `Asynchronous/Middleware/SendMessageMiddleware` class has been moved to the `Middleware` namespace

diff --git a/src/Symfony/Component/Messenger/MessageBus.php b/src/Symfony/Component/Messenger/MessageBus.php
@@ -50,11 +50,12 @@ public function getIterator()
     /**
      * {@inheritdoc}
      */
-    public function dispatch($message): void
+    public function dispatch($message): Envelope
     {
         if (!\is_object($message)) {
             throw new \TypeError(sprintf('Invalid argument provided to "%s()": expected object, but got %s.', __METHOD__, \gettype($message)));
         }
+        $envelope = $message instanceof Envelope ? $message : new Envelope($message);
         $middlewareIterator = $this->middlewareAggregate->getIterator();
 
         while ($middlewareIterator instanceof \IteratorAggregate) {
@@ -63,10 +64,10 @@ public function dispatch($message): void
         $middlewareIterator->rewind();
 
         if (!$middlewareIterator->valid()) {
-            return;
+            return $envelope;
         }
         $stack = new StackMiddleware($middlewareIterator);
 
-        $middlewareIterator->current()->handle($message instanceof Envelope ? $message : new Envelope($message), $stack);
+        return $middlewareIterator->current()->handle($envelope, $stack);
     }
 }
diff --git a/src/Symfony/Component/Messenger/MessageBusInterface.php b/src/Symfony/Component/Messenger/MessageBusInterface.php
@@ -21,5 +21,5 @@ interface MessageBusInterface
      *
      * @param object|Envelope $message The message or the message pre-wrapped in an envelope
      */
-    public function dispatch($message): void;
+    public function dispatch($message): Envelope;
 }
diff --git a/src/Symfony/Component/Messenger/Middleware/ActivationMiddleware.php b/src/Symfony/Component/Messenger/Middleware/ActivationMiddleware.php
@@ -35,12 +35,12 @@ public function __construct(MiddlewareInterface $inner, $activated)
     /**
      * {@inheritdoc}
      */
-    public function handle(Envelope $envelope, StackInterface $stack): void
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope
     {
         if (\is_callable($this->activated) ? ($this->activated)($envelope) : $this->activated) {
-            $this->inner->handle($envelope, $stack);
-        } else {
-            $stack->next()->handle($envelope, $stack);
+            return $this->inner->handle($envelope, $stack);
         }
+
+        return $stack->next()->handle($envelope, $stack);
     }
 }
diff --git a/src/Symfony/Component/Messenger/Middleware/HandleMessageMiddleware.php b/src/Symfony/Component/Messenger/Middleware/HandleMessageMiddleware.php
@@ -34,13 +34,14 @@ public function __construct(HandlerLocatorInterface $messageHandlerLocator, bool
      *
      * @throws NoHandlerForMessageException When no handler is found and $allowNoHandlers is false
      */
-    public function handle(Envelope $envelope, StackInterface $stack): void
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope
     {
         if (null !== $handler = $this->messageHandlerLocator->getHandler($envelope)) {
             $handler($envelope->getMessage());
-            $stack->next()->handle($envelope, $stack);
         } elseif (!$this->allowNoHandlers) {
             throw new NoHandlerForMessageException(sprintf('No handler for message "%s".', \get_class($envelope->getMessage())));
         }
+
+        return $stack->next()->handle($envelope, $stack);
     }
 }
diff --git a/src/Symfony/Component/Messenger/Middleware/LoggingMiddleware.php b/src/Symfony/Component/Messenger/Middleware/LoggingMiddleware.php
@@ -29,7 +29,7 @@ public function __construct(LoggerInterface $logger)
     /**
      * {@inheritdoc}
      */
-    public function handle(Envelope $envelope, StackInterface $stack): void
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope
     {
         $message = $envelope->getMessage();
         $context = array(
@@ -39,7 +39,7 @@ public function handle(Envelope $envelope, StackInterface $stack): void
         $this->logger->debug('Starting handling message {name}', $context);
 
         try {
-            $stack->next()->handle($envelope, $stack);
+            $envelope = $stack->next()->handle($envelope, $stack);
         } catch (\Throwable $e) {
             $context['exception'] = $e;
             $this->logger->warning('An exception occurred while handling message {name}', $context);
@@ -48,5 +48,7 @@ public function handle(Envelope $envelope, StackInterface $stack): void
         }
 
         $this->logger->debug('Finished handling message {name}', $context);
+
+        return $envelope;
     }
 }
diff --git a/src/Symfony/Component/Messenger/Middleware/MiddlewareInterface.php b/src/Symfony/Component/Messenger/Middleware/MiddlewareInterface.php
@@ -18,5 +18,5 @@
  */
 interface MiddlewareInterface
 {
-    public function handle(Envelope $envelope, StackInterface $stack): void;
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope;
 }
diff --git a/src/Symfony/Component/Messenger/Middleware/SendMessageMiddleware.php b/src/Symfony/Component/Messenger/Middleware/SendMessageMiddleware.php
@@ -34,26 +34,24 @@ public function __construct(SenderLocatorInterface $senderLocator, array $messag
     /**
      * {@inheritdoc}
      */
-    public function handle(Envelope $envelope, StackInterface $stack): void
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope
     {
         if ($envelope->get(ReceivedStamp::class)) {
             // It's a received message. Do not send it back:
-            $stack->next()->handle($envelope, $stack);
-
-            return;
+            return $stack->next()->handle($envelope, $stack);
         }
 
         $sender = $this->senderLocator->getSender($envelope);
 
         if ($sender) {
-            $sender->send($envelope);
+            $envelope = $sender->send($envelope);
 
             if (!AbstractSenderLocator::getValueFromMessageRouting($this->messagesToSendAndHandleMapping, $envelope)) {
                 // message has no corresponding handler
-                return;
+                return $envelope;
             }
         }
 
-        $stack->next()->handle($envelope, $stack);
+        return $stack->next()->handle($envelope, $stack);
     }
 }
diff --git a/src/Symfony/Component/Messenger/Middleware/StackMiddleware.php b/src/Symfony/Component/Messenger/Middleware/StackMiddleware.php
@@ -41,8 +41,8 @@ public function next(): MiddlewareInterface
         return $iterator->current();
     }
 
-    public function handle(Envelope $envelope, StackInterface $stack): void
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope
     {
-        // no-op: this is the last null middleware
+        return $envelope;
     }
 }
diff --git a/src/Symfony/Component/Messenger/Middleware/TraceableMiddleware.php b/src/Symfony/Component/Messenger/Middleware/TraceableMiddleware.php
@@ -37,7 +37,7 @@ public function __construct(MiddlewareInterface $inner, Stopwatch $stopwatch, st
     /**
      * {@inheritdoc}
      */
-    public function handle(Envelope $envelope, StackInterface $stack): void
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope
     {
         $class = \get_class($this->inner);
         $eventName = 'c' === $class[0] && 0 === strpos($class, "class@anonymous\0") ? get_parent_class($class).'@anonymous' : $class;
@@ -49,7 +49,7 @@ public function handle(Envelope $envelope, StackInterface $stack): void
         $this->stopwatch->start($eventName, $this->eventCategory);
 
         try {
-            $this->inner->handle($envelope, new TraceableInnerMiddleware($stack, $this->stopwatch, $eventName, $this->eventCategory));
+            return $this->inner->handle($envelope, new TraceableInnerMiddleware($stack, $this->stopwatch, $eventName, $this->eventCategory));
         } finally {
             if ($this->stopwatch->isStarted($eventName)) {
                 $this->stopwatch->stop($eventName);
@@ -79,15 +79,17 @@ public function __construct(StackInterface $stack, Stopwatch $stopwatch, string
     /**
      * {@inheritdoc}
      */
-    public function handle(Envelope $envelope, StackInterface $stack): void
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope
     {
         $this->stopwatch->stop($this->eventName);
         if ($this === $stack) {
-            $this->stack->next()->handle($envelope, $this->stack);
+            $envelope = $this->stack->next()->handle($envelope, $this->stack);
         } else {
-            $stack->next()->handle($envelope, $stack);
+            $envelope = $stack->next()->handle($envelope, $stack);
         }
         $this->stopwatch->start($this->eventName, $this->eventCategory);
+
+        return $envelope;
     }
 
     /**

diff --git a/src/Symfony/Component/Messenger/Middleware/ValidationMiddleware.php b/src/Symfony/Component/Messenger/Middleware/ValidationMiddleware.php
@@ -31,7 +31,7 @@ public function __construct(ValidatorInterface $validator)
     /**
      * {@inheritdoc}
      */
-    public function handle(Envelope $envelope, StackInterface $stack): void
+    public function handle(Envelope $envelope, StackInterface $stack): Envelope
     {
         $message = $envelope->getMessage();
         $groups = null;
@@ -45,6 +45,6 @@ public function handle(Envelope $envelope, StackInterface $stack): void
             throw new ValidationFailedException($message, $violations);
         }
 
-        $stack->next()->handle($envelope, $stack);
+        return $stack->next()->handle($envelope, $stack);
     }
 }
diff --git a/src/Symfony/Component/Messenger/Tests/DataCollector/MessengerDataCollectorTest.php b/src/Symfony/Component/Messenger/Tests/DataCollector/MessengerDataCollectorTest.php
@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Messenger\DataCollector\MessengerDataCollector;
+use Symfony\Component\Messenger\Envelope;
 use Symfony\Component\Messenger\MessageBusInterface;
 use Symfony\Component\Messenger\Tests\Fixtures\DummyMessage;
 use Symfony\Component\Messenger\TraceableMessageBus;
@@ -36,9 +37,10 @@ protected function setUp()
     public function testHandle()
     {
         $message = new DummyMessage('dummy message');
+        $envelope = new Envelope($message);
 
         $bus = $this->getMockBuilder(MessageBusInterface::class)->getMock();
-        $bus->method('dispatch')->with($message);
+        $bus->method('dispatch')->with($message)->willReturn($envelope);
         $bus = new TraceableMessageBus($bus);
 
         $collector = new MessengerDataCollector();
@@ -124,9 +126,11 @@ public function testHandleWithException()
     public function testKeepsOrderedDispatchCalls()
     {
         $firstBus = $this->getMockBuilder(MessageBusInterface::class)->getMock();
+        $firstBus->method('dispatch')->willReturn(new Envelope(new \stdClass()));
         $firstBus = new TraceableMessageBus($firstBus);
 
         $secondBus = $this->getMockBuilder(MessageBusInterface::class)->getMock();
+        $secondBus->method('dispatch')->willReturn(new Envelope(new \stdClass()));
         $secondBus = new TraceableMessageBus($secondBus);
 
         $collector = new MessengerDataCollector();

diff --git a/src/Symfony/Component/Messenger/Tests/DependencyInjection/MessengerPassTest.php b/src/Symfony/Component/Messenger/Tests/DependencyInjection/MessengerPassTest.php
@@ -847,8 +847,8 @@ public function dummyMethodForSomeBus()
 
 class UselessMiddleware implements MiddlewareInterface
 {
-    public function handle(Envelope $message, StackInterface $stack): void
+    public function handle(Envelope $message, StackInterface $stack): Envelope
     {
-        $stack->next()->handle($message, $stack);
+        return $stack->next()->handle($message, $stack);
     }
 }
diff --git a/src/Symfony/Component/Messenger/Tests/MessageBusTest.php b/src/Symfony/Component/Messenger/Tests/MessageBusTest.php
@@ -49,13 +49,14 @@ public function testItCallsMiddleware()
             ->method('handle')
             ->with($envelope, $this->anything())
             ->will($this->returnCallback(function ($envelope, $stack) {
-                $stack->next()->handle($envelope, $stack);
+                return $stack->next()->handle($envelope, $stack);
             }));
 
         $secondMiddleware = $this->getMockBuilder(MiddlewareInterface::class)->getMock();
         $secondMiddleware->expects($this->once())
             ->method('handle')
             ->with($envelope, $this->anything())
+            ->willReturn($envelope)
         ;
 
         $bus = new MessageBus(array(
@@ -77,21 +78,22 @@ public function testThatAMiddlewareCanAddSomeStampsToTheEnvelope()
             ->method('handle')
             ->with($envelope, $this->anything())
             ->will($this->returnCallback(function ($envelope, $stack) {
-                $stack->next()->handle($envelope->with(new AnEnvelopeStamp()), $stack);
+                return $stack->next()->handle($envelope->with(new AnEnvelopeStamp()), $stack);
             }));
 
         $secondMiddleware = $this->getMockBuilder(MiddlewareInterface::class)->getMock();
         $secondMiddleware->expects($this->once())
             ->method('handle')
             ->with($envelopeWithAnotherStamp, $this->anything())
             ->will($this->returnCallback(function ($envelope, $stack) {
-                $stack->next()->handle($envelope, $stack);
+                return $stack->next()->handle($envelope, $stack);
             }));
 
         $thirdMiddleware = $this->getMockBuilder(MiddlewareInterface::class)->getMock();
         $thirdMiddleware->expects($this->once())
             ->method('handle')
             ->with($envelopeWithAnotherStamp, $this->anything())
+            ->willReturn($envelopeWithAnotherStamp)
         ;
 
         $bus = new MessageBus(array(
@@ -116,13 +118,14 @@ public function testThatAMiddlewareCanUpdateTheMessageWhileKeepingTheEnvelopeSta
             ->method('handle')
             ->with($envelope, $this->anything())
             ->will($this->returnCallback(function ($envelope, $stack) use ($expectedEnvelope) {
-                $stack->next()->handle($expectedEnvelope, $stack);
+                return $stack->next()->handle($expectedEnvelope, $stack);
             }));
 
         $secondMiddleware = $this->getMockBuilder(MiddlewareInterface::class)->getMock();
         $secondMiddleware->expects($this->once())
             ->method('handle')
             ->with($expectedEnvelope, $this->anything())
+            ->willReturn($envelope)
         ;
 
         $bus = new MessageBus(array(

diff --git a/src/Symfony/Component/Messenger/Tests/Middleware/ActivationMiddlewareTest.php b/src/Symfony/Component/Messenger/Tests/Middleware/ActivationMiddlewareTest.php
@@ -31,7 +31,7 @@ public function testExecuteMiddlewareOnActivated()
         $stack->expects($this->never())->method('next');
 
         $middleware = $this->createMock(MiddlewareInterface::class);
-        $middleware->expects($this->once())->method('handle')->with($envelope, $stack);
+        $middleware->expects($this->once())->method('handle')->with($envelope, $stack)->willReturn($envelope);
 
         $decorator = new ActivationMiddleware($middleware, true);
 
@@ -50,7 +50,7 @@ public function testExecuteMiddlewareOnActivatedWithCallable()
         $stack->expects($this->never())->method('next');
 
         $middleware = $this->createMock(MiddlewareInterface::class);
-        $middleware->expects($this->once())->method('handle')->with($envelope, $stack);
+        $middleware->expects($this->once())->method('handle')->with($envelope, $stack)->willReturn($envelope);
 
         $decorator = new ActivationMiddleware($middleware, $activated);
 

diff --git a/src/Symfony/Component/Messenger/Tests/Middleware/HandleMessageMiddlewareTest.php b/src/Symfony/Component/Messenger/Tests/Middleware/HandleMessageMiddlewareTest.php
@@ -50,6 +50,6 @@ public function testAllowNoHandlers()
     {
         $middleware = new HandleMessageMiddleware(new HandlerLocator(array()), true);
 
-        $this->assertNull($middleware->handle(new Envelope(new DummyMessage('Hey')), new StackMiddleware()));
+        $this->assertInstanceOf(Envelope::class, $middleware->handle(new Envelope(new DummyMessage('Hey')), new StackMiddleware()));
     }
 }
diff --git a/src/Symfony/Component/Messenger/Tests/Middleware/MiddlewareTestCase.php b/src/Symfony/Component/Messenger/Tests/Middleware/MiddlewareTestCase.php
@@ -23,6 +23,9 @@ protected function getStackMock(bool $nextIsCalled = true)
         $nextMiddleware
             ->expects($nextIsCalled ? $this->once() : $this->never())
             ->method('handle')
+            ->will($this->returnCallback(function ($envelope, StackInterface $stack) {
+                return $envelope;
+            }))
         ;
 
         $stack = $this->createMock(StackInterface::class);