Skip to content

Tweaks to messenger docs based on feedback from @Tobion #11639

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
Jun 3, 2019
Merged

Tweaks to messenger docs based on feedback from @Tobion #11639

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
44 changes: 26 additions & 18 deletions messenger.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,7 @@ Handling Messages Synchronously

If a message doesn't :ref:`match any routing rules <messenger-routing>`, it won't
be sent to any transport and will be handled immediately. In some cases (like
when :ref:`sending handlers to different transports<messenger-handlers-different-transports>`),
when `binding handlers to different transports`_),
it's easier or more flexible to handle this explicitly: by creating a ``sync``
transport and "sending" messages there to be handled immediately:

Expand Down Expand Up @@ -709,7 +709,11 @@ to retry them:
$ php bin/console messenger:failed:retry 20 30 --force

# remove a message without retrying it
$ php bin/console messenger:failed:retry 20
$ php bin/console messenger:failed:remove 20

If the messages fails again, it will be re-sent back to the failure transport
due to the normal `retry rules <Retries & Failures>`_. Once the max retry has
been hit, the message will be discarded permanently.

.. _messenger-transports-config:

Expand Down Expand Up @@ -773,12 +777,17 @@ a table named ``messenger_messages`` (this is configurable) when the transport i
first used. You can disable that with the ``auto_setup`` option and set the table
up manually by calling the ``messenger:setup-transports`` command.

.. caution::
.. tip::

To avoid tools like Doctrine Migrations from trying to remove this table because
it's not part of your normal schema, you can set the ``schema_filter`` option:

If you use Doctrine Migrations, each generated migration will try to drop
the ``messenger_messages`` table and needs to be removed manually. You
cannot (yet) use ``doctrine.dbal.schema_filter`` to avoid. See
https://github.com/symfony/symfony/issues/31623.
.. code-block:: yaml

# config/packages/doctrine.yaml
doctrine:
dbal:
schema_filter: '~^(?!messenger_messages)~'

The transport has a number of options:

Expand Down Expand Up @@ -842,14 +851,14 @@ Options defined under ``options`` take precedence over ones defined in the DSN.
================== =================================== =======
table_name Name of the table messenger_messages
queue_name Name of the queue (a column in the default
table, to use-use one table for
table, to use one table for
multiple transports)
redeliver_timeout Timeout before retrying a messages 3600
that's in the queue but in the
"handling" state (if a worker died
for some reason, this will occur,
eventually you should retry the
message)
message) - in seconds.
auto_setup Whether the table should be created
automatically during send / get. true
================== =================================== =======
Expand All @@ -875,7 +884,7 @@ a running Redis server (^5.0).

The Redis transport does not support "delayed" messages.

A number of options can be configured via the DSN of via the ``options`` key
A number of options can be configured via the DSN or via the ``options`` key
under the transport in ``messenger.yaml``:

================== =================================== =======
Expand Down Expand Up @@ -1065,9 +1074,7 @@ A handler class can handle multiple messages or configure itself by implementing
}
}

.. _messenger-handlers-different-transports:

Sending Handlers to Different Transports
Binding Handlers to Different Transports
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Each message can have multiple handlers, and when a message is consumed
Expand Down Expand Up @@ -1239,17 +1246,18 @@ collection of middleware (and their order). By default, the middleware configure
for each bus looks like this:

#. ``add_bus_name_stamp_middleware`` - adds a stamp to record which bus this
message was dispatched into.
message was dispatched into;

#. ``dispatch_after_current_bus``- see :doc:`/messenger/message-recorder`.
#. ``dispatch_after_current_bus``- see :doc:`/messenger/message-recorder`;

#. ``failed_message_processing_middleware`` - sends failed messages to the
:ref:`failure transport <messenger-failure-transport>`.
#. ``failed_message_processing_middleware`` - processes messages that are being
retried via the :ref:`failure transport <messenger-failure-transport>` to make
them properly function as if they were being received from their original transport;

#. Your own collection of middleware_;

#. ``send_message`` - if routing is configured for the transport, this sends
messages to that transport and stops the middleware chain.
messages to that transport and stops the middleware chain;

#. ``handle_message`` - calls the message handler(s) for the given message.

Expand Down