[Messenger] Backport some changes from 4.2 branch

Author: ogizanagi

components/messenger.rst

@@ -38,8 +38,8 @@ Concepts
    something can be a message broker or a third party API for example.
 
 **Receiver**:
-   Responsible for deserializing and forwarding messages to handler(s). This
-   can be a message queue puller or an API endpoint for example.
+   Responsible for retrieving, deserializing and forwarding messages to handler(s).
+   This can be a message queue puller or an API endpoint for example.
 
 **Handler**:
    Responsible for handling messages using the business logic applicable to the messages.
@@ -55,7 +55,7 @@ are configured for you:
 
 #. ``LoggingMiddleware`` (logs the processing of your messages)
 #. ``SendMessageMiddleware`` (enables asynchronous processing)
-#. ``HandleMessageMiddleware`` (calls the registered handle)
+#. ``HandleMessageMiddleware`` (calls the registered handler)
 
 Example::
 
@@ -206,7 +206,7 @@ First, create your sender::
 Your own Receiver
 ~~~~~~~~~~~~~~~~~
 
-A receiver is responsible for receiving messages from a source and dispatching
+A receiver is responsible for getting messages from a source and dispatching
 them to the application.
 
 Imagine you already processed some "orders" in your application using a
@@ -226,7 +226,7 @@ First, create your receiver::
     use Symfony\Component\Serializer\SerializerInterface;
     use Symfony\Component\Messenger\Envelope;
 
-    class NewOrdersFromCsvFile implements ReceiverInterface
+    class NewOrdersFromCsvFileReceiver implements ReceiverInterface
     {
        private $serializer;
        private $filePath;

messenger.rst

@@ -84,7 +84,9 @@ message handler. It's a class with an ``__invoke`` method::
 
 Message handlers must be registered as services and :doc:`tagged </service_container/tags>`
 with the ``messenger.message_handler`` tag. If you're using the
-:ref:`default services.yaml configuration <service-container-services-load-example>`,
+:ref:`default services.yaml configuration <service-container-services-load-example>` and implement
+:class:`Symfony\\Component\\Messenger\\Handler\\MessageHandlerInterface`
+or :class:`Symfony\\Component\\Messenger\\Handler\\MessageSubscriberInterface`,
 this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
 
 If you're not using service autoconfiguration, then you need to add this config:
@@ -543,11 +545,16 @@ for each bus looks like this:
 #. ``call_message_handler`` middleware. Will call the message handler(s) for the
    given message.
 
-Adding your own Middleware
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note::
 
-As described in the component documentation, you can add your own middleware
-within the buses to add some extra capabilities like this:
+    These middleware names are actually shortcuts working by convention.
+    The real service ids are prefixed with the ``messenger.middleware.`` namespace.
+
+Disabling default Middleware
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you don't want the default collection of middleware to be present on your bus,
+you can disable them like this:
 
 .. configuration-block::
 
@@ -558,9 +565,7 @@ within the buses to add some extra capabilities like this:
             messenger:
                 buses:
                     messenger.bus.default:
-                        middleware:
-                            - 'App\Middleware\MyMiddleware'
-                            - 'App\Middleware\AnotherMiddleware'
+                        default_middleware: false
 
     .. code-block:: xml
 
@@ -576,10 +581,7 @@ within the buses to add some extra capabilities like this:
 
             <framework:config>
                 <framework:messenger>
-                    <framework:bus name="messenger.bus.default">
-                        <framework:middleware id="App\Middleware\MyMiddleware" />
-                        <framework:middleware id="App\Middleware\AnotherMiddleware" />
-                    </framework:bus>
+                    <framework:bus name="messenger.bus.default" default-middleware="false" />
                 </framework:messenger>
             </framework:config>
         </container>
@@ -591,23 +593,17 @@ within the buses to add some extra capabilities like this:
             'messenger' => array(
                 'buses' => array(
                     'messenger.bus.default' => array(
-                        'middleware' => array(
-                            'App\Middleware\MyMiddleware',
-                            'App\Middleware\AnotherMiddleware',
-                        ),
+                        'default_middleware' => false,
                     ),
                 ),
             ),
         ));
 
-Note that if the service is abstract, a different instance of service will be
-created per bus.
-
-Disabling default Middleware
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Adding your own Middleware
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you don't want the default collection of middleware to be present on your bus,
-you can disable them like this:
+As described in the component documentation, you can add your own middleware
+within the buses to add some extra capabilities like this:
 
 .. configuration-block::
 
@@ -618,7 +614,9 @@ you can disable them like this:
             messenger:
                 buses:
                     messenger.bus.default:
-                        default_middleware: false
+                        middleware:
+                            - 'App\Middleware\MyMiddleware'
+                            - 'App\Middleware\AnotherMiddleware'
 
     .. code-block:: xml
 
@@ -634,7 +632,10 @@ you can disable them like this:
 
             <framework:config>
                 <framework:messenger>
-                    <framework:bus name="messenger.bus.default" default-middleware="false" />
+                    <framework:bus name="messenger.bus.default">
+                        <framework:middleware id="App\Middleware\MyMiddleware" />
+                        <framework:middleware id="App\Middleware\AnotherMiddleware" />
+                    </framework:bus>
                 </framework:messenger>
             </framework:config>
         </container>
@@ -646,12 +647,18 @@ you can disable them like this:
             'messenger' => array(
                 'buses' => array(
                     'messenger.bus.default' => array(
-                        'default_middleware' => false,
+                        'middleware' => array(
+                            'App\Middleware\MyMiddleware',
+                            'App\Middleware\AnotherMiddleware',
+                        ),
                     ),
                 ),
             ),
         ));
 
+Note that if the service is abstract, a different instance of service will be
+created per bus.
+
 Using Middleware Factories
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -674,13 +681,13 @@ factories. Defining such requires a two-step configuration based on Symfony's
 
             # Step 2: an abstract definition that will call the factory with default
             # arguments or the ones provided in the middleware config
-            messenger.middleware.doctrine_transaction_middleware:
+            messenger.middleware.doctrine_transaction:
                 class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware
                 factory: 'doctrine.orm.messenger.middleware_factory.transaction:createMiddleware'
                 abstract: true
                 # the default arguments to use when none provided from config. Example:
                 # middleware:
-                #     - doctrine_transaction_middleware: ~
+                #     - doctrine_transaction: ~
                 arguments: ['default']
 
     .. code-block:: xml
@@ -703,7 +710,7 @@ factories. Defining such requires a two-step configuration based on Symfony's
 
                 <!-- Step 2: an abstract definition that will call the factory with default
                      arguments or the ones provided in the middleware config -->
-                <service id="messenger.middleware.doctrine_transaction_middleware"
+                <service id="messenger.middleware.doctrine_transaction"
                     class="Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware"
                     abstract="true">
 
@@ -729,7 +736,7 @@ factories. Defining such requires a two-step configuration based on Symfony's
 
         // Step 2: an abstract definition that will call the factory with default
         // arguments or the ones provided in the middleware config
-        $container->register('messenger.middleware.doctrine_transaction_middleware', DoctrineTransactionMiddleware::class)
+        $container->register('messenger.middleware.doctrine_transaction', DoctrineTransactionMiddleware::class)
             ->setFactory(array(
                 new Reference('doctrine.orm.messenger.middleware_factory.transaction'),
                 'createMiddleware'
@@ -742,7 +749,7 @@ which is the argument expected by the
 ``Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory::createMiddleware`` method.
 
 Then you can reference and configure the
-``messenger.middleware.doctrine_transaction_middleware`` service as a middleware:
+``messenger.middleware.doctrine_transaction`` service as a middleware:
 
 .. configuration-block::
 
@@ -755,9 +762,9 @@ Then you can reference and configure the
                     command_bus:
                         middleware:
                             # Using defaults
-                            - doctrine_transaction_middleware
+                            - doctrine_transaction
                             # Using another entity manager
-                            - doctrine_transaction_middleware: ['custom']
+                            - doctrine_transaction: ['custom']
 
     .. code-block:: xml
 
@@ -775,9 +782,9 @@ Then you can reference and configure the
                 <framework:messenger>
                     <framework:bus name="command_bus">
                         <!-- Using defaults -->
-                        <framework:middleware id="doctrine_transaction_middleware" />
+                        <framework:middleware id="doctrine_transaction" />
                         <!-- Using another entity manager -->
-                        <framework:middleware id="doctrine_transaction_middleware">
+                        <framework:middleware id="doctrine_transaction">
                             <framework:argument>custom</framework:argument>
                         </framework:middleware>
                     </framework:bus>
@@ -794,20 +801,15 @@ Then you can reference and configure the
                     'command_bus' => array(
                         'middleware' => array(
                             // Using defaults
-                            'doctrine_transaction_middleware',
+                            'doctrine_transaction',
                             // Using another entity manager
-                            array('id' => 'doctrine_transaction_middleware', 'arguments' => array('custom')),
+                            array('id' => 'doctrine_transaction', 'arguments' => array('custom')),
                         ),
                     ),
                 ),
             ),
         ));
 
-.. note::
-
-    The ``doctrine_transaction_middleware`` shortcut is a convention. The real
-    service id is prefixed with the ``messenger.middleware.`` namespace.
-
 .. note::
 
     Middleware factories only allow scalar and array arguments in config (no
@@ -816,9 +818,9 @@ Then you can reference and configure the
 
 .. tip::
 
-    The ``doctrine_transaction_middleware`` is a built-in middleware wired
-    automatically when the DoctrineBundle and the Messenger component are
-    installed and enabled.
+    The ``messenger.middleware.doctrine_transaction`` middleware is a built-in
+    middleware wired automatically when the DoctrineBundle and the Messenger
+    component are installed and enabled.
 
 Your own Transport
 ------------------