Skip to content

Add documentation for the Redis transport #11341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 11, 2019
Merged

Add documentation for the Redis transport #11341

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 60 additions & 25 deletions messenger.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,8 +135,12 @@ Transports
By default, messages are processed as soon as they are dispatched. If you prefer
to process messages asynchronously, you must configure a transport. These
transports communicate with your application via queuing systems or third parties.
The built-in AMQP transport allows you to communicate with most of the AMQP
brokers such as RabbitMQ.

There are the following built-in transports:

- AMQP
- Doctrine
- Redis

.. note::

Expand All @@ -155,7 +159,7 @@ the messenger component, the following configuration should have been created:
framework:
messenger:
transports:
amqp: "%env(MESSENGER_TRANSPORT_DSN)%"
your_transport: "%env(MESSENGER_TRANSPORT_DSN)%"

.. code-block:: xml

Expand All @@ -171,7 +175,7 @@ the messenger component, the following configuration should have been created:

<framework:config>
<framework:messenger>
<framework:transport name="amqp" dsn="%env(MESSENGER_TRANSPORT_DSN)%"/>
<framework:transport name="your_transport" dsn="%env(MESSENGER_TRANSPORT_DSN)%"/>
</framework:messenger>
</framework:config>
</container>
Expand All @@ -182,33 +186,63 @@ the messenger component, the following configuration should have been created:
$container->loadFromExtension('framework', [
'messenger' => [
'transports' => [
'amqp' => '%env(MESSENGER_TRANSPORT_DSN)%',
'your_transport' => '%env(MESSENGER_TRANSPORT_DSN)%',
],
],
]);

This will also configure the following services for you:

#. A ``messenger.sender.your_transport`` sender to be used when routing messages;
#. A ``messenger.receiver.your_transport`` receiver to be used when consuming messages.

Now define the ``MESSENGER_TRANSPORT_DSN`` in the ``.env`` file.
See examples beneath how to configure the DSN for different transports.

Amqp
~~~~

.. code-block:: bash

# .env
###> symfony/messenger ###
MESSENGER_TRANSPORT_DSN=amqp://guest:guest@localhost:5672/%2f/messages
###< symfony/messenger ###

This is enough to allow you to route your message to the ``amqp`` transport.
This will also configure the following services for you:

#. A ``messenger.sender.amqp`` sender to be used when routing messages;
#. A ``messenger.receiver.amqp`` receiver to be used when consuming messages.

.. note::

In order to use Symfony's built-in AMQP transport, you will need the AMQP
PHP extension and the Serializer Component. Ensure that they are installed with:
PHP extension and the Serializer component. Ensure that they are installed with:

.. code-block:: terminal

$ composer require symfony/amqp-pack

Redis
~~~~~

The Redis transport will use `streams`_ to queue messages.

.. code-block:: bash

# .env
MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages

This is enough to allow you to route your message to the Redis transport.

If you have multiple systems to receive the same messages you could use different groups
to achieve this:

.. code-block:: bash

# .env
MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages/group1/consumer1

.. note::

In order to use Symfony's built-in Redis transport, you will need the Redis
PHP extension (^4.2), a running Redis server (^5.0) and the Serializer component.

Routing
-------

Expand All @@ -225,7 +259,7 @@ configuration:
framework:
messenger:
routing:
'My\Message\Message': amqp # The name of the defined transport
'My\Message\Message': your_transport # The name of the defined transport

.. code-block:: xml

Expand All @@ -242,7 +276,7 @@ configuration:
<framework:config>
<framework:messenger>
<framework:routing message-class="My\Message\Message">
<framework:sender service="amqp"/>
<framework:sender service="your_transport"/>
</framework:routing>
</framework:messenger>
</framework:config>
Expand All @@ -254,7 +288,7 @@ configuration:
$container->loadFromExtension('framework', [
'messenger' => [
'routing' => [
'My\Message\Message' => 'amqp',
'My\Message\Message' => 'your_transport',
],
],
]);
Expand All @@ -274,7 +308,7 @@ instead of a class name:
messenger:
routing:
'My\Message\MessageAboutDoingOperationalWork': another_transport
'*': amqp
'*': your_transport

.. code-block:: xml

Expand All @@ -294,7 +328,7 @@ instead of a class name:
<framework:sender service="another_transport"/>
</framework:routing>
<framework:routing message-class="*">
<framework:sender service="amqp"/>
<framework:sender service="your_transport"/>
</framework:routing>
</framework:messenger>
</framework:config>
Expand All @@ -307,7 +341,7 @@ instead of a class name:
'messenger' => [
'routing' => [
'My\Message\Message' => 'another_transport',
'*' => 'amqp',
'*' => 'your_transport',
],
],
]);
Expand All @@ -322,7 +356,7 @@ A class of messages can also be routed to multiple senders by specifying a list:
framework:
messenger:
routing:
'My\Message\ToBeSentToTwoSenders': [amqp, audit]
'My\Message\ToBeSentToTwoSenders': [your_transport, audit]

.. code-block:: xml

Expand All @@ -339,7 +373,7 @@ A class of messages can also be routed to multiple senders by specifying a list:
<framework:config>
<framework:messenger>
<framework:routing message-class="My\Message\ToBeSentToTwoSenders">
<framework:sender service="amqp"/>
<framework:sender service="your_transport"/>
<framework:sender service="audit"/>
</framework:routing>
</framework:messenger>
Expand All @@ -352,7 +386,7 @@ A class of messages can also be routed to multiple senders by specifying a list:
$container->loadFromExtension('framework', [
'messenger' => [
'routing' => [
'My\Message\ToBeSentToTwoSenders' => ['amqp', 'audit'],
'My\Message\ToBeSentToTwoSenders' => ['your_transport', 'audit'],
],
],
]);
Expand All @@ -369,7 +403,7 @@ while still having them passed to their respective handler:
messenger:
routing:
'My\Message\ThatIsGoingToBeSentAndHandledLocally':
senders: [amqp]
senders: [your_transport]
send_and_handle: true

.. code-block:: xml
Expand All @@ -387,7 +421,7 @@ while still having them passed to their respective handler:
<framework:config>
<framework:messenger>
<framework:routing message-class="My\Message\ThatIsGoingToBeSentAndHandledLocally" send-and-handle="true">
<framework:sender service="amqp"/>
<framework:sender service="your_transport"/>
</framework:routing>
</framework:messenger>
</framework:config>
Expand All @@ -400,7 +434,7 @@ while still having them passed to their respective handler:
'messenger' => [
'routing' => [
'My\Message\ThatIsGoingToBeSentAndHandledLocally' => [
'senders' => ['amqp'],
'senders' => ['your_transport'],
'send_and_handle' => true,
],
],
Expand All @@ -415,7 +449,7 @@ most of the cases. To do so, use the ``messenger:consume`` command like this:

.. code-block:: terminal

$ php bin/console messenger:consume amqp
$ php bin/console messenger:consume your_transport

The first argument is the receiver's service name. It might have been created by
your ``transports`` configuration or it can be your own receiver.
Expand Down Expand Up @@ -835,3 +869,4 @@ Learn more
/messenger/*

.. _`enqueue's transport`: https://github.com/php-enqueue/messenger-adapter
.. _`streams`: https://redis.io/topics/streams-intro