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::