Merge branch '4.2'

* 4.2:
  Update micro_kernel_trait.rst
  Recommend registering the error handler in prod
  validator: comparison constraints value
  Minor fixes in the Doctrine listeners article
  [Messenger] Added a trait for synchronous query & command buses

Author: javiereguiluz

components/debug.rst

@@ -37,8 +37,8 @@ tools.
 
 .. caution::
 
-    You should never enable the debug tools in a production environment as
-    they might disclose sensitive information to the user.
+    You should never enable the debug tools, except for the error handler, in a
+    production environment as they might disclose sensitive information to the user.
 
 Enabling the Error Handler
 --------------------------
@@ -52,6 +52,9 @@ fatal errors)::
 
     ErrorHandler::register();
 
+This error handler is enabled by default in the production environment when the
+application uses the FrameworkBundle because it generates better error logs.
+
 Enabling the Exception Handler
 ------------------------------
 

configuration/micro_kernel_trait.rst

@@ -55,7 +55,7 @@ Next, create an ``index.php`` file that defines the kernel class and executes it
         {
             // kernel is a service that points to this class
             // optional 3rd argument is the route name
-            $routes->add('/random/{limit}', 'Kernel::randomNumber');
+            $routes->add('/random/{limit}', 'kernel::randomNumber');
         }
 
         public function randomNumber($limit)

doctrine/event_listeners_subscribers.rst

@@ -129,7 +129,7 @@ entity), you should check for the entity's class type in your method
 
     In Doctrine 2.4, a feature called Entity Listeners was introduced.
     It is a lifecycle listener class used for an entity. You can read
-    about it in `the Doctrine Documentation`_.
+    about it in `the DoctrineBundle documentation`_.
 
 Creating the Subscriber Class
 -----------------------------
@@ -199,9 +199,6 @@ fired.
 That's why it is preferable to use entity listeners instead of subscribers
 whenever possible.
 
-.. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
-.. _`the Doctrine Documentation`: https://symfony.com/doc/current/bundles/DoctrineBundle/entity-listeners.html
-
 Priorities for Event Listeners
 ------------------------------
 
@@ -256,3 +253,6 @@ numbers mean that listeners are invoked earlier.
             ->autowire(MyLowPriorityListener::class)
             ->addTag('doctrine.event_listener', ['event' => 'postPersist', 'priority' => 1])
         ;
+
+.. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
+.. _`the DoctrineBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineBundle/entity-listeners.html

messenger/handler_results.rst

@@ -0,0 +1,117 @@
+.. index::
+    single: Messenger; Getting results / Working with command & query buses
+
+Getting Results from your Handler
+---------------------------------
+
+When a message is handled, the :class:`Symfony\\Component\\Messenger\\Middleware\\HandleMessageMiddleware`
+adds a :class:`Symfony\\Component\\Messenger\\Stamp\\HandledStamp` for each object that handled the message.
+You can use this to get the value returned by the handler(s):
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        use Symfony\Component\Messenger\MessageBusInterface;
+        use Symfony\Component\Messenger\Stamp\HandledStamp;
+
+        $envelope = $messageBus->dispatch(SomeMessage());
+
+        // get the value that was returned by the last message handler
+        $handledStamp = $envelope->last(HandledStamp::class);
+        $handledStamp->getResult();
+
+        // or get info about all of handlers
+        $handledStamps = $envelope->all(HandledStamp::class);
+
+A :class:`Symfony\\Component\\Messenger\\HandleTrait` also exists in order to ease
+leveraging a Messenger bus for synchronous needs.
+The :method:`Symfony\\Component\\Messenger\\HandleTrait::handle` method ensures
+there is exactly one handler registered and returns its result.
+
+Working with Command & Query Buses
+----------------------------------
+
+The Messenger component can be used in CQRS architectures where command & query
+buses are central pieces of the application. Read Martin Fowler's
+`article about CQRS`_ to learn more and
+:doc:`how to configure multiple buses </messenger/multiple_buses>`.
+
+As queries are usually synchronous and expected to be handled once,
+getting the result from the handler is a common need.
+
+To make this easy, you can leverage the ``HandleTrait`` in any class that has
+a ``$messageBus`` property:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        // src/Action/ListItems.php
+        namespace App\Action;
+
+        use App\Message\ListItemsQuery;
+        use App\MessageHandler\ListItemsQueryResult;
+        use Symfony\Component\Messenger\HandleTrait;
+        use Symfony\Component\Messenger\MessageBusInterface;
+
+        class ListItems
+        {
+            use HandleTrait;
+
+            public function __construct(MessageBusInterface $messageBus)
+            {
+                $this->messageBus = $messageBus;
+            }
+
+            public function __invoke()
+            {
+                $result = $this->query(new ListItemsQuery(/* ... */));
+
+                // Do something with the result
+                // ...
+            }
+
+            // Creating such a method is optional, but allows type-hinting the result
+            private function query(ListItemsQuery $query): ListItemsResult
+            {
+                return $this->handle($query);
+            }
+        }
+
+Hence, you can use the trait to create command & query bus classes.
+For example, you could create a special ``QueryBus`` class and inject it
+wherever you need a query bus behavior instead of the ``MessageBusInterface``:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        // src/MessageBus/QueryBus.php
+        namespace App\MessageBus;
+
+        use Symfony\Component\Messenger\Envelope;
+        use Symfony\Component\Messenger\HandleTrait;
+        use Symfony\Component\Messenger\MessageBusInterface;
+
+        class QueryBus
+        {
+            use HandleTrait;
+
+            public function __construct(MessageBusInterface $messageBus)
+            {
+                $this->messageBus = $messageBus;
+            }
+
+            /**
+             * @param object|Envelope $query
+             *
+             * @return mixed The handler returned value
+             */
+            public function query($query)
+            {
+                return $this->handle($query);
+            }
+        }
+
+.. _`article about CQRS`: https://martinfowler.com/bliki/CQRS.html

reference/constraints/EqualTo.rst

@@ -75,7 +75,7 @@ and that the ``age`` is ``20``, you could do the following:
             <class name="App\Entity\Person">
                 <property name="firstName">
                     <constraint name="EqualTo">
-                        <value>Mary</value>
+                        Mary
                     </constraint>
                 </property>
                 <property name="age">

reference/constraints/GreaterThan.rst

@@ -74,7 +74,7 @@ The following constraints ensure that:
             <class name="App\Entity\Person">
                 <property name="siblings">
                     <constraint name="GreaterThan">
-                        <value>5</value>
+                        5
                     </constraint>
                 </property>
                 <property name="age">

reference/constraints/GreaterThanOrEqual.rst

@@ -72,7 +72,7 @@ The following constraints ensure that:
             <class name="App\Entity\Person">
                 <property name="siblings">
                     <constraint name="GreaterThanOrEqual">
-                        <value>5</value>
+                        5
                     </constraint>
                 </property>
                 <property name="age">

reference/constraints/IdenticalTo.rst

@@ -78,7 +78,7 @@ The following constraints ensure that:
             <class name="App\Entity\Person">
                 <property name="firstName">
                     <constraint name="IdenticalTo">
-                        <value>Mary</value>
+                        Mary
                     </constraint>
                 </property>
                 <property name="age">

reference/constraints/LessThan.rst

@@ -74,7 +74,7 @@ The following constraints ensure that:
             <class name="App\Entity\Person">
                 <property name="siblings">
                     <constraint name="LessThan">
-                        <value>5</value>
+                        5
                     </constraint>
                 </property>
                 <property name="age">

reference/constraints/LessThanOrEqual.rst

@@ -72,7 +72,7 @@ The following constraints ensure that:
             <class name="App\Entity\Person">
                 <property name="siblings">
                     <constraint name="LessThanOrEqual">
-                        <value>5</value>
+                        5
                     </constraint>
                 </property>
                 <property name="age">

reference/constraints/NotEqualTo.rst

@@ -77,7 +77,7 @@ the following:
             <class name="App\Entity\Person">
                 <property name="firstName">
                     <constraint name="NotEqualTo">
-                        <value>Mary</value>
+                        Mary
                     </constraint>
                 </property>
                 <property name="age">

reference/constraints/NotIdenticalTo.rst

@@ -78,7 +78,7 @@ The following constraints ensure that:
             <class name="App\Entity\Person">
             <property name="firstName">
                     <constraint name="NotIdenticalTo">
-                        <value>Mary</value>
+                        Mary
                     </constraint>
                 </property>
                 <property name="age">