tweaks to messenger docs based on feedback from @Tobion

weaverryan · weaverryan · commit 872c019b7ca9 · 2019-05-31T15:23:54.000-04:00
diff --git a/messenger.rst b/messenger.rst
@@ -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:
 
@@ -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:
+
+    .. code-block:: yaml
 
-    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.
+        # config/packages/doctrine.yaml
+        doctrine:
+            dbal:
+                schema_filter: '~^(?!messenger_messages)~'
 
 The transport has a number of options:
 
@@ -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
 ==================  =================================== =======
@@ -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``:
 
 ==================  =================================== =======
@@ -1067,7 +1076,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
@@ -1243,8 +1252,9 @@ for each bus looks like this:
 
 #. ``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_;
 
