Merge branch '2.8' into 3.2

* 2.8: (37 commits)
  [#8192] use path() in PHP templates
  Reworded the article about form login redirects
  Explained the edge-case where the use_referer option doesn't work
  [#7572] fix wording
  [#7585] remove trailing whitespaces
  [#7585] minor rewording
  Fixed a typo
  Fixed a typo
  Update parent_services for tip consistency
  [#7685] use the method role
  Minor change
  Updating doc to specify priority of default normalizer
  [#7767] remove trailing space
  [#7767] replace "options" with "entry_options"
  [#7767] minor rewording
  [#8047] add inline code comment
  Fixed the issue in a different way
  Jquery datePicker syntax update
  [#8104] minor rewording
  Add more precision about automatic provider assignation
  ...

Author: xabbuh

components/http_foundation.rst

@@ -153,7 +153,7 @@ exist::
     // returns 'baz'
 
 When PHP imports the request query, it handles request parameters like
-``foo[bar]=bar`` in a special way as it creates an array. So you can get the
+``foo[bar]=baz`` in a special way as it creates an array. So you can get the
 ``foo`` parameter and you will get back an array with a ``bar`` element::
 
     // the query string is '?foo[bar]=baz'

components/validator.rst

@@ -46,6 +46,8 @@ characters long::
         }
     }
 
+The validator returns the list of violations.
+
 Retrieving a Validator Instance
 -------------------------------
 

controller/service.rst

@@ -23,17 +23,19 @@ These are the main **advantages** of defining controllers as services:
   service container configuration. This is useful when developing reusable bundles;
 * Your controllers are more "sandboxed". By looking at the constructor arguments,
   it's easy to see what types of things this controller may or may not do;
+* If you're not passing some required dependencies or if you are injecting some
+  non-existent services, you'll get errors during the container compilation
+  instead of during runtime execution;
 * Since dependencies must be injected manually, it's more obvious when your
   controller is becoming too big (i.e. if you have many constructor arguments).
 
 These are the main **drawbacks** of defining controllers as services:
 
-* It takes more work to create the controllers because they don't have
-  automatic access to the services or to the base controller shortcuts;
+* It takes more work to create the controllers and they become more verbose
+  because they don't have automatic access to the services and the base
+  controller shortcuts;
 * The constructor of the controllers can rapidly become too complex because you
-  must inject every single dependency needed by them;
-* The code of the controllers is more verbose because you can't use the shortcuts
-  of the base controller and you must replace them with some lines of code.
+  must inject every single dependency needed by them.
 
 The recommendation from the :doc:`best practices </best_practices/controllers>`
 is also valid for controllers defined as services: avoid putting your business

forms.rst

@@ -562,10 +562,10 @@ the correct values of a number of field options.
     field ``nullable``). This is very useful, as your client-side validation will
     automatically match your validation rules.
 
-``max_length``
-    If the field is some sort of text field, then the ``max_length`` option can be
-    guessed from the validation constraints (if ``Length`` or ``Range`` is used) or
-    from the Doctrine metadata (via the field's length).
+``maxlength``
+    If the field is some sort of text field, then the ``maxlength`` option attribute
+    can be guessed from the validation constraints (if ``Length`` or ``Range`` is used)
+    or from the Doctrine metadata (via the field's length).
 
 .. caution::
 

page_creation.rst

@@ -68,12 +68,7 @@ random) number and prints it. To do that, create a "Controller class" and a
 Before diving into this, test it out! If you are using PHP's internal web server
 go to:
 
-    http://localhost:8000/app_dev.php/lucky/number
-
-.. tip::
-
-    If you're using the built-in PHP web-server, you can omit the ``app_dev.php``
-    part of the URL.
+    http://localhost:8000/lucky/number
 
 If you see a lucky number being printed back to you, congratulations! But before
 you run off to play the lottery, check out how this works. Remember the two steps

reference/configuration/security.rst

@@ -414,7 +414,14 @@ use_referer
 **type**: ``boolean`` **default**: ``false``
 
 If ``true``, the user is redirected to the value stored in the ``HTTP_REFERER``
-header when no previous URL was stored in the session.
+header when no previous URL was stored in the session. If the referrer URL is
+the same as the one generated with the ``login_path`` route, the user is
+redirected to the ``default_target_path`` to avoid a redirection loop.
+
+.. note::
+
+    For historical reasons, and to match the misspelling of the HTTP standard,
+    the option is called ``use_referer`` instead of ``use_referrer``.
 
 .. _reference-security-pbkdf2:
 

reference/dic_tags.rst

@@ -1003,6 +1003,10 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface`.
 
 For more details, see :doc:`/serializer`.
 
+The priorities of the default normalizers can be found in the
+:method:`Symfony\\Bundle\\FrameworkBundle\\DependencyInjection\\FrameworkExtension::registerSerializerConfiguration`
+method.
+
 swiftmailer.default.plugin
 --------------------------
 

reference/forms/types/collection.rst

@@ -277,6 +277,15 @@ form you have to set this option to true. However, existing collection entries
 will only be deleted if you have the allow_delete_ option enabled. Otherwise
 the empty values will be kept.
 
+.. caution::
+
+    The ``delete_empty`` option only removes items when the normalized value is
+    ``null``. If the nested `type`_ is a compound form type, you must either set
+    the ``required`` option to ``false`` or set the ``empty_data`` option to 
+    ``null``. Both of these options can be set inside `entry_options`_. Read
+    about the :ref:`form's empty_data option <reference-form-option-empty-data>`
+    to learn why this is necessary.
+
 entry_options
 ~~~~~~~~~~~~~
 

reference/forms/types/date.rst

@@ -101,12 +101,14 @@ make the following changes::
         'attr' => ['class' => 'js-datepicker'],
     ));
 
-Assuming you're using jQuery, you can initialize the date picker via:
+Then, add the following JavaScript code in your template to initialize the date
+picker:
 
 .. code-block:: html
 
     <script>
         $(document).ready(function() {
+            // configure the bootstrap datepicker
             $('.js-datepicker').datepicker({
                 format: 'yyyy-mm-dd'
             });

reference/forms/types/form.rst

@@ -71,6 +71,8 @@ option on the form.
 
 .. include:: /reference/forms/types/options/data_class.rst.inc
 
+.. _reference-form-option-empty-data:
+
 .. include:: /reference/forms/types/options/empty_data.rst.inc
     :end-before: DEFAULT_PLACEHOLDER