Merge branch '2.8' into 3.4

* 2.8:
  [#10545] minor tweaks for the example
  Update form.rst
  Update service_decoration.rst
  Rename content_type header to content-type
  Reduce potential confusion in priority explanation
  [standards] Document "phpdoc_types_order"

Author: javiereguiluz

components/event_dispatcher.rst

@@ -147,11 +147,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

@@ -154,6 +154,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
 ~~~~~~~~~~~~~~~
 

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

@@ -602,7 +602,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

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 AppBundle\Mailer definition with the new one, the
             # old definition is lost
             AppBundle\Mailer:
-                class: AppBundle\DecoratingMailer
+                class: AppBundle\NewMailer
 
     .. code-block:: xml
 
@@ -33,25 +32,27 @@ the original service is lost:
 
                 <!-- this replaces the old AppBundle\Mailer definition with the new
                      one, the old definition is lost -->
-                <service id="AppBundle\Mailer" class="AppBundle\DecoratingMailer" />
+                <service id="AppBundle\Mailer" class="AppBundle\NewMailer" />
             </services>
         </container>
 
     .. code-block:: php
 
         // config/services.php
         use AppBundle\Mailer;
-        use AppBundle\DecoratingMailer;
+        use AppBundle\NewMailer;
 
         $container->register(Mailer::class);
 
         // this replaces the old AppBundle\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.decorating_mailer.inner``:
 
 .. configuration-block::