|
| 1 | +.. index:: |
| 2 | + single: Messenger; Getting results / Working with command & query buses |
| 3 | + |
| 4 | +Getting Results from your Handler |
| 5 | +--------------------------------- |
| 6 | + |
| 7 | +When a message is handled, the :class:`Symfony\\Component\\Messenger\\Middleware\\HandleMessageMiddleware` |
| 8 | +adds a :class:`Symfony\\Component\\Messenger\\Stamp\\HandledStamp` for each object that handled the message. |
| 9 | +You can use this to get the value returned by the handler(s): |
| 10 | + |
| 11 | +.. configuration-block:: |
| 12 | + |
| 13 | + .. code-block:: php |
| 14 | +
|
| 15 | + use Symfony\Component\Messenger\MessageBusInterface; |
| 16 | + use Symfony\Component\Messenger\Stamp\HandledStamp; |
| 17 | +
|
| 18 | + $envelope = $messageBus->dispatch(SomeMessage()); |
| 19 | +
|
| 20 | + // get the value that was returned by the last message handler |
| 21 | + $handledStamp = $envelope->last(HandledStamp::class); |
| 22 | + $handledStamp->getResult(); |
| 23 | +
|
| 24 | + // or get info about all of handlers |
| 25 | + $handledStamps = $envelope->all(HandledStamp::class); |
| 26 | +
|
| 27 | +A :class:`Symfony\\Component\\Messenger\\HandleTrait` also exists in order to ease |
| 28 | +leveraging a Messenger bus for synchronous needs. |
| 29 | +The :method:`Symfony\\Component\\Messenger\\HandleTrait::handle` method ensures |
| 30 | +there is exactly one handler registered and returns its result. |
| 31 | + |
| 32 | +Working with command & query buses |
| 33 | +---------------------------------- |
| 34 | + |
| 35 | +The Messenger component can be used in CQRS architectures where command & query |
| 36 | +buses are central pieces of the application. |
| 37 | +See Martin Fowler's `article about CQRS`_ to learn more and :doc:`how to configure multiple buses </messenger/multiple_buses>`. |
| 38 | + |
| 39 | +As queries are usually synchronous and expected to be handled once, |
| 40 | +getting the result from the handler is a common need. |
| 41 | + |
| 42 | +To make this easy, you can leverage the ``HandleTrait`` in any class that has |
| 43 | +a ``$messageBus`` property: |
| 44 | + |
| 45 | +.. configuration-block:: |
| 46 | + |
| 47 | + .. code-block:: php |
| 48 | +
|
| 49 | + // src/Action/ListItems.php |
| 50 | +
|
| 51 | + namespace App\Action; |
| 52 | +
|
| 53 | + use App\Message\ListItemsQuery; |
| 54 | + use App\MessageHandler\ListItemsQueryResult; |
| 55 | + use Symfony\Component\Messenger\HandleTrait; |
| 56 | + use Symfony\Component\Messenger\MessageBusInterface; |
| 57 | +
|
| 58 | + class ListItems |
| 59 | + { |
| 60 | + use HandleTrait; |
| 61 | +
|
| 62 | + public function __construct(MessageBusInterface $messageBus) |
| 63 | + { |
| 64 | + $this->messageBus = $messageBus; |
| 65 | + } |
| 66 | +
|
| 67 | + public function __invoke() |
| 68 | + { |
| 69 | + $result = $this->query(new ListItemsQuery(/* ... */)); |
| 70 | +
|
| 71 | + // Do something with the result |
| 72 | + // ... |
| 73 | + } |
| 74 | +
|
| 75 | + // Creating such a method is optional, but allows type-hinting the result |
| 76 | + private function query(ListItemsQuery $query): ListItemsResult |
| 77 | + { |
| 78 | + return $this->handle($query); |
| 79 | + } |
| 80 | + } |
| 81 | +
|
| 82 | +Hence, you can use the trait to create command & query bus classes. |
| 83 | +For example, you could create a special ``QueryBus`` class and inject it |
| 84 | +wherever you need a query bus behavior instead of the ``MessageBusInterface``: |
| 85 | + |
| 86 | +.. configuration-block:: |
| 87 | + |
| 88 | + .. code-block:: php |
| 89 | +
|
| 90 | + // src/MessageBus/QueryBus.php |
| 91 | +
|
| 92 | + namespace App\MessageBus; |
| 93 | +
|
| 94 | + use Symfony\Component\Messenger\Envelope; |
| 95 | + use Symfony\Component\Messenger\HandleTrait; |
| 96 | + use Symfony\Component\Messenger\MessageBusInterface; |
| 97 | +
|
| 98 | + class QueryBus |
| 99 | + { |
| 100 | + use HandleTrait; |
| 101 | +
|
| 102 | + public function __construct(MessageBusInterface $messageBus) |
| 103 | + { |
| 104 | + $this->messageBus = $messageBus; |
| 105 | + } |
| 106 | +
|
| 107 | + /** |
| 108 | + * @param object|Envelope $query |
| 109 | + * |
| 110 | + * @return mixed The handler returned value |
| 111 | + */ |
| 112 | + public function query($query) |
| 113 | + { |
| 114 | + return $this->handle($query); |
| 115 | + } |
| 116 | + } |
| 117 | +
|
| 118 | +.. _article about CQRS: https://martinfowler.com/bliki/CQRS.html |
0 commit comments