Merge branch '4.1'

* 4.1:
  [symfony#10545] minor tweaks for the example
  Update form.rst
  [Messenger] Improve the Messenger Handler Example
  fix directory tree markup
  Update service_decoration.rst
  Rename content_type header to content-type
  Reduce potential confusion in priority explanation
  Update configuration_organization.rst
  [standards] Document "phpdoc_types_order"

Author: javiereguiluz

components/event_dispatcher.rst

@@ -146,11 +146,10 @@ The ``addListener()`` method takes up to three arguments:
 
 #. The event name (string) that this listener wants to listen to;
 #. A PHP callable that will be executed when the specified event is dispatched;
-#. An optional priority integer (higher equals more important and therefore
-   that the listener will be triggered earlier) that determines when a listener
-   is triggered versus other listeners (defaults to ``0``). If two listeners
-   have the same priority, they are executed in the order that they were
-   added to the dispatcher.
+#. An optional priority, defined as a positive or negative integer (defaults to
+   ``0``). The higher the priority, the earlier the listener is called. If two 
+   listeners have the same priority, they are executed in the order that they
+   were added to the dispatcher.
 
 .. note::
 

components/form.rst

@@ -155,6 +155,13 @@ the CSRF generator and validated when binding the form.
         $csrfStorage = new NativeSessionTokenStorage();
         // ...
 
+You can disable CSRF protection per form using the ``csrf_protection`` option::
+
+    use Symfony\\Component\\Form\\Extension\\Core\\Type\\FormType
+
+    $form = $formFactory->createBuilder(FormType::class, null, ['csrf_protection' => false])
+        ->getForm();
+
 Twig Templating
 ~~~~~~~~~~~~~~~
 

configuration/configuration_organization.rst

@@ -49,18 +49,18 @@ this structure:
 
     your-project/
     ├─ config/
-    │  └─ packages/
-    │     ├─ dev/
-    |     │  ├─ framework.yaml
-    │     │  └─ ...
-    │     ├─ prod/
-    │     │  └─ ...
-    │     ├─ test/
-    │     │  └─ ...
-    |     ├─ framework.yaml
-    │     └─ ...
-    │     ├─ services.yaml
-    │     └─ services_dev.yaml
+    │  ├─ packages/
+    │  │  ├─ dev/
+    │  │  │  ├─ framework.yaml
+    │  │  │  └─ ...
+    │  │  ├─ prod/
+    │  │  │  └─ ...
+    │  │  ├─ test/
+    │  │  │  └─ ...
+    │  │  ├─ framework.yaml
+    │  │  └─ ...
+    │  ├─ services.yaml
+    │  └─ services_dev.yaml
     ├─ ...
 
 This default structure was chosen for its simplicity — one file per package and

contributing/code/standards.rst

@@ -194,7 +194,10 @@ Structure
 
 * Do not use spaces around ``[`` offset accessor and before ``]`` offset accessor;
 
-* Add a ``use`` statement for every class that is not part of the global namespace.
+* Add a ``use`` statement for every class that is not part of the global namespace;
+
+* When PHPDoc tags like ``@param`` or ``@return`` include ``null`` and other
+  types, always place ``null`` at the end of the list of types.
 
 Naming Conventions
 ~~~~~~~~~~~~~~~~~~

controller.rst

@@ -522,7 +522,7 @@ the ``Request`` class::
 
         // retrieves an HTTP request header, with normalized, lowercase keys
         $request->headers->get('host');
-        $request->headers->get('content_type');
+        $request->headers->get('content-type');
     }
 
 The ``Request`` class has several public properties and methods that return any

create_framework/http_foundation.rst

@@ -192,7 +192,7 @@ fingertips thanks to a nice and simple API::
 
     // retrieve an HTTP request header, with normalized, lowercase keys
     $request->headers->get('host');
-    $request->headers->get('content_type');
+    $request->headers->get('content-type');
 
     $request->getMethod();    // GET, POST, PUT, DELETE, HEAD
     $request->getLanguages(); // an array of languages the client accepts

introduction/http_fundamentals.rst

@@ -231,7 +231,7 @@ have all the request information at your fingertips::
 
     // retrieves an HTTP request header, with normalized, lowercase keys
     $request->headers->get('host');
-    $request->headers->get('content_type');
+    $request->headers->get('content-type');
 
     $request->getMethod();    // e.g. GET, POST, PUT, DELETE or HEAD
     $request->getLanguages(); // an array of languages the client accepts

messenger.rst

@@ -19,6 +19,28 @@ install messenger before using it:
 
     $ composer require messenger
 
+Message
+-------
+
+Before you can send a message, you must create it first. There is no specific
+requirement for a message, except it should be serializable and unserializable
+by a Symfony Serializer instance::
+
+    // src/Message/SmsNotification.php
+    namespace App\Message;
+
+    class SmsNotification
+    {
+        private $content;
+
+        public function __construct(string $content)
+        {
+            $this->content = $content;
+        }
+
+        // ...getters
+    }
+
 Using the Messenger Service
 ---------------------------
 
@@ -28,15 +50,15 @@ you need it, like in a controller::
     // src/Controller/DefaultController.php
     namespace App\Controller;
 
-    use App\Message\SendNotification;
+    use App\Message\SmsNotification;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\Messenger\MessageBusInterface;
 
     class DefaultController extends AbstractController
     {
         public function index(MessageBusInterface $bus)
         {
-            $bus->dispatch(new SendNotification('A string to be sent...'));
+            $bus->dispatch(new SmsNotification('A string to be sent...'));
         }
     }
 
@@ -46,14 +68,15 @@ Registering Handlers
 In order to do something when your message is dispatched, you need to create a
 message handler. It's a class with an ``__invoke`` method::
 
-    // src/MessageHandler/MyMessageHandler.php
+    // src/MessageHandler/SmsNotificationHandler.php
     namespace App\MessageHandler;
 
+    use App\Message\SmsNotification;
     use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
 
-    class MyMessageHandler implements MessageHandlerInterface
+    class SmsNotificationHandler implements MessageHandlerInterface
     {
-        public function __invoke(MyMessage $message)
+        public function __invoke(SmsNotification $message)
         {
             // do something with it.
         }
@@ -74,7 +97,7 @@ If you're not using service autoconfiguration, then you need to add this config:
 
         # config/services.yaml
         services:
-            App\MessageHandler\MyMessageHandler:
+            App\MessageHandler\SmsNotificationHandler:
                 tags: [messenger.message_handler]
 
     .. code-block:: xml
@@ -87,7 +110,7 @@ If you're not using service autoconfiguration, then you need to add this config:
                 http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\MessageHandler\MyMessageHandler">
+                <service id="App\MessageHandler\SmsNotificationHandler">
                    <tag name="messenger.message_handler" />
                 </service>
             </services>
@@ -96,9 +119,9 @@ If you're not using service autoconfiguration, then you need to add this config:
     .. code-block:: php
 
         // config/services.php
-        use App\MessageHandler\MyMessageHandler;
+        use App\MessageHandler\SmsNotificationHandler;
 
-        $container->register(MyMessageHandler::class)
+        $container->register(SmsNotificationHandler::class)
             ->addTag('messenger.message_handler');
 
 .. note::

service_container/service_decoration.rst

@@ -4,8 +4,7 @@
 How to Decorate Services
 ========================
 
-When overriding an existing definition (e.g. when applying the `Decorator pattern`_),
-the original service is lost:
+When overriding an existing definition, the original service is lost:
 
 .. configuration-block::
 
@@ -18,7 +17,7 @@ the original service is lost:
             # this replaces the old App\Mailer definition with the new one, the
             # old definition is lost
             App\Mailer:
-                class: App\DecoratingMailer
+                class: App\NewMailer
 
     .. code-block:: xml
 
@@ -33,25 +32,27 @@ the original service is lost:
 
                 <!-- this replaces the old App\Mailer definition with the new
                      one, the old definition is lost -->
-                <service id="App\Mailer" class="App\DecoratingMailer" />
+                <service id="App\Mailer" class="App\NewMailer" />
             </services>
         </container>
 
     .. code-block:: php
 
         // config/services.php
         use App\Mailer;
-        use App\DecoratingMailer;
+        use App\NewMailer;
 
         $container->register(Mailer::class);
 
         // this replaces the old App\Mailer definition with the new one, the
         // old definition is lost
-        $container->register(Mailer::class, DecoratingMailer::class);
+        $container->register(Mailer::class, NewMailer::class);
 
 Most of the time, that's exactly what you want to do. But sometimes,
-you might want to decorate the old service instead and keep the old service so
-that you can reference it:
+you might want to decorate the old one instead (i.e. apply the `Decorator pattern`_).
+In this case, the old service should be kept around to be able to reference
+it in the new one. This configuration replaces ``App\Mailer`` with a new one,
+but keeps a reference of the old one as ``App\DecoratingMailer.inner``:
 
 .. configuration-block::