[Messenger] Added a trait for synchronous query & command buses

Author: ogizanagi

components/messenger.rst

@@ -298,5 +298,14 @@ loop, the message bus will add a :class:`Symfony\\Component\\Messenger\\Stamp\\R
 stamp to the message envelopes and the :class:`Symfony\\Component\\Messenger\\Middleware\\SendMessageMiddleware`
 middleware will know it should not route these messages again to a transport.
 
+Learn more
+----------
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    /messenger
+    /messenger/*
+
 .. _blog posts about command buses: https://matthiasnoback.nl/tags/command%20bus/
 .. _SimpleBus project: http://simplebus.io

messenger.rst

@@ -928,4 +928,12 @@ will give you access to the following services:
 #. ``messenger.sender.yours``: the sender;
 #. ``messenger.receiver.yours``: the receiver.
 
+Learn more
+----------
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    /messenger/*
+
 .. _`enqueue's transport`: https://github.com/php-enqueue/messenger-adapter

messenger/handler_results.rst

@@ -0,0 +1,127 @@
+.. index::
+    single: Messenger; Getting results / Working with command & query buses
+
+Getting results
+---------------
+
+When a message is handled, the :class:`Symfony\\Component\\Messenger\\Middleware\\HandleMessageMiddleware`
+adds a :class:`Symfony\\Component\\Messenger\\Stamp\\HandledStamp` for each responding handler,
+which can be used to get their returned value:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        use Symfony\Component\Messenger\MessageBusInterface;
+        use Symfony\Component\Messenger\Stamp\HandledStamp;
+
+        $envelope = $messageBus->dispatch(SomeMessage());
+
+        // Get the last handled stamp and its returned value:
+        $handledStamp = $envelope->last(HandledStamp::class);
+        $handledStamp->getResult();
+
+Using the :method:`Symfony\\Component\\Messenger\\Stamp\\HandledStamp::last` method
+assumes there is only one configured handler or that only the last handler
+result is relevant. But you can also get the stamps for all handlers:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        use Symfony\Component\Messenger\MessageBusInterface;
+        use Symfony\Component\Messenger\Stamp\HandledStamp;
+
+        $envelope = $messageBus->dispatch(SomeMessage());
+        $handledStamps = $envelope->all(HandledStamp::class);
+
+A :class:`Symfony\\Component\\Messenger\\HandleTrait` also exists in order to ease
+leveraging a Messenger bus for synchronous needs.
+The :method:`Symfony\\Component\\Messenger\\HandleTrait::handle` method ensures
+there is exactly one handler registered and returns its result.
+
+Working with command & query buses
+----------------------------------
+
+The Messenger component can be used in CQRS architectures where command & query
+buses are central pieces of the application.
+See Martin Fowler's `article about CQRS`_ to learn more and :doc:`how to configure multiple buses </messenger/multiple_buses>`.
+
+As queries are usually synchronous and expect to be handled once, getting the
+result from the handler is a common need.
+
+You can directly leverage the ``HandleTrait`` trait in a controller (or any caller):
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        namespace App\Controller;
+
+        use App\Message\ListItemsQuery;
+        use App\MessageHandler\ListItemsQueryResult;
+        use Symfony\Component\Messenger\HandleTrait;
+        use Symfony\Component\Messenger\MessageBusInterface;
+
+        class ListItemsController
+        {
+            use HandleTrait;
+
+            public function __construct(MessageBusInterface $messageBus)
+            {
+                $this->messageBus = $messageBus;
+            }
+
+            public function __invoke(Request $request)
+            {
+                // Extract data from the request
+                //...
+
+                $result = $this->query(new ListItemsQuery(/* ... */));
+
+                // Return a response with result
+                // ...
+            }
+
+            // Creating such a method is optional, but allows type-hinting the result
+            private function query(ListItemsQuery $query): ListItemsResult
+            {
+                return $this->handle($query);
+            }
+        }
+
+Or you can use the trait to create command & query buses classes.
+Here is how you can create a ``QueryBus`` class to inject in places you need
+a query bus behavior instead of the ``MessageBusInterface``:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        namespace App\MessageBus;
+
+        use Symfony\Component\Messenger\Envelope;
+        use Symfony\Component\Messenger\HandleTrait;
+        use Symfony\Component\Messenger\MessageBusInterface;
+
+        class QueryBus
+        {
+            use HandleTrait;
+
+            public function __construct(MessageBusInterface $messageBus)
+            {
+                $this->messageBus = $messageBus;
+            }
+
+            /**
+             * @param object|Envelope $query
+             *
+             * @return mixed The handler returned value
+             */
+            public function query($query)
+            {
+                return $this->handle($query);
+            }
+        }
+
+.. _article about CQRS: https://martinfowler.com/bliki/CQRS.html