Merge branch '2.7' into 2.8

* 2.7: (26 commits)
  moving options below basic usage
  changing a few orders of sections - mostly to move overridden after the main options
  Rewrite note a bit
  fix capitalization
  [Cookbook][Assetic] complete a sentence
  Fixed a typo
  Reordered two overridden options
  Added missing types in overridden options
  Fixed the order of the different options
  Fixed the order of the different options
  Improved the explanation about the "compoun" option
  Fixer minor issues
  Fixed errors noticed by Wouter
  Removed a duplicated "trim" option in the "password" type
  Removed again a duplicated option explanation
  Removed a duplicated option explanation in "file" type
  Extracted the common "data_class" option explanation for data-related types
  Documented the overridden options of "date" type
  Documented overridden options for "file" type
  Documented the overridden options of the "password" type
  ...

cookbook/assetic/php.rst

@@ -116,7 +116,8 @@ formatter used by the filter to produce the compiled CSS file. Using the
 compressed formatter will minimize the the resulting file, regardless of whether
 the original files are regular CSS files or SCSS files.
 
-Next, your Twig template to add the ``{% stylesheets %}`` tag defined by Assetic:
+Next, update your Twig template to add the ``{% stylesheets %}`` tag defined
+by Assetic:
 
 .. code-block:: html+jinja
 

cookbook/form/form_customization.rst

@@ -114,6 +114,12 @@ fragment needed to render every part of a form:
   but the CSS classes applied are the ones used to display the forms horizontally
   (i.e. the label and the widget in the same row).
 
+.. caution::
+
+    When you use the Bootstrap form themes and render the fields manually,
+    calling ``form_label()`` for a checkbox/radio field doesn't show anything.
+    Due to Bootstrap internals, the label is already shown by ``form_widget()``.
+
 In the next section you will learn how to customize a theme by overriding
 some or all of its fragments.
 

cookbook/security/form_login_setup.rst

@@ -456,7 +456,7 @@ firewall matches *all* URLs, including ``/login_check``). If ``/login_check``
 doesn't match any firewall, you'll receive a ``Unable to find the controller
 for path "/login_check"`` exception.
 
-4. Multiple Firewalls Don't Share the same Security Context
+4. Multiple Firewalls Don't Share the Same Security Context
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you're using multiple firewalls and you authenticate against one firewall,

reference/forms/types/country.rst

@@ -23,7 +23,7 @@ you should just use the ``choice`` type directly.
 | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`)          |
 +-------------+-----------------------------------------------------------------------+
 | Overridden  | - `choices`_                                                          |
-| Options     |                                                                       |
+| options     |                                                                       |
 +-------------+-----------------------------------------------------------------------+
 | Inherited   | from the :doc:`choice </reference/forms/types/choice>` type           |
 | options     |                                                                       |

reference/forms/types/currency.rst

@@ -17,7 +17,7 @@ you should just use the ``choice`` type directly.
 | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`)           |
 +-------------+------------------------------------------------------------------------+
 | Overridden  | - `choices`_                                                           |
-| Options     |                                                                        |
+| options     |                                                                        |
 +-------------+------------------------------------------------------------------------+
 | Inherited   | from the :doc:`choice </reference/forms/types/choice>` type            |
 | options     |                                                                        |

reference/forms/types/date.rst

@@ -30,7 +30,9 @@ day and year) or three select boxes (see the `widget`_ option).
 |                      | - `widget`_                                                                 |
 |                      | - `years`_                                                                  |
 +----------------------+-----------------------------------------------------------------------------+
-| Overridden Options   | - `by_reference`_                                                           |
+| Overridden options   | - `by_reference`_                                                           |
+|                      | - `compound`_                                                               |
+|                      | - `data_class`_                                                             |
 |                      | - `error_bubbling`_                                                         |
 +----------------------+-----------------------------------------------------------------------------+
 | Inherited            | - `data`_                                                                   |
@@ -132,6 +134,10 @@ by_reference
 
 The ``DateTime`` classes are treated as immutable objects.
 
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
+.. include:: /reference/forms/types/options/data_class_date.rst.inc
+
 error_bubbling
 ~~~~~~~~~~~~~~
 

reference/forms/types/datetime.rst

@@ -34,6 +34,11 @@ the data can be a ``DateTime`` object, a string, a timestamp or an array.
 |                      | - `with_seconds`_                                                           |
 |                      | - `years`_                                                                  |
 +----------------------+-----------------------------------------------------------------------------+
+| Overridden options   | - `by_reference`_                                                           |
+|                      | - `compound`_                                                               |
+|                      | - `data_class`_                                                             |
+|                      | - `error_bubbling`_                                                         |
++----------------------+-----------------------------------------------------------------------------+
 | Inherited            | - `data`_                                                                   |
 | options              | - `disabled`_                                                               |
 |                      | - `inherit_data`_                                                           |
@@ -134,6 +139,25 @@ with the `date_widget`_ and `time_widget`_ options.
 
 .. include:: /reference/forms/types/options/years.rst.inc
 
+Overridden Options
+------------------
+
+by_reference
+~~~~~~~~~~~~
+
+**default**: ``false``
+
+The ``DateTime`` classes are treated as immutable objects.
+
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
+.. include:: /reference/forms/types/options/data_class_date.rst.inc
+
+error_bubbling
+~~~~~~~~~~~~~~
+
+**default**: ``false``
+
 Inherited Options
 -----------------
 

reference/forms/types/entity.rst

@@ -19,7 +19,7 @@ objects from the database.
 |             | - `property`_                                                    |
 |             | - `query_builder`_                                               |
 +-------------+------------------------------------------------------------------+
-| Overriden   | - `choice_list`_                                                 |
+| Overridden  | - `choice_list`_                                                 |
 | options     | - `choices`_                                                     |
 +-------------+------------------------------------------------------------------+
 | Inherited   | from the :doc:`choice </reference/forms/types/choice>` type:     |

reference/forms/types/file.rst

@@ -11,9 +11,12 @@ The ``file`` type represents a file input in your form.
 +-------------+---------------------------------------------------------------------+
 | Options     | - `multiple`_                                                       |
 +-------------+---------------------------------------------------------------------+
+| Overridden  | - `compound`_                                                       |
+| options     | - `data_class`_                                                     |
+|             | - `empty_data`_                                                     |
++-------------+---------------------------------------------------------------------+
 | Inherited   | - `disabled`_                                                       |
-| options     | - `empty_data`_                                                     |
-|             | - `error_bubbling`_                                                 |
+| options     | - `error_bubbling`_                                                 |
 |             | - `error_mapping`_                                                  |
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
@@ -86,6 +89,26 @@ multiple
 
 When set to true, the user will be able to upload multiple files at the same time.
 
+Overridden Options
+------------------
+
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
+data_class
+~~~~~~~~~~
+
+**type**: ``string`` **default**: :class:`Symfony\\Component\\HttpFoundation\\File\\File`
+
+This option sets the appropriate file-related data mapper to be used by the type.
+
+empty_data
+~~~~~~~~~~
+
+**type**: ``mixed`` **default**: ``null``
+
+This option determines what value the field will return when the submitted
+value is empty.
+
 Inherited Options
 -----------------
 
@@ -94,14 +117,6 @@ type:
 
 .. include:: /reference/forms/types/options/disabled.rst.inc
 
-.. include:: /reference/forms/types/options/empty_data.rst.inc
-    :end-before: DEFAULT_PLACEHOLDER
-
-The default value is ``null``.
-
-.. include:: /reference/forms/types/options/empty_data.rst.inc
-    :start-after: DEFAULT_PLACEHOLDER
-
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
 .. include:: /reference/forms/types/options/error_mapping.rst.inc

reference/forms/types/hidden.rst

@@ -9,8 +9,9 @@ The hidden type represents a hidden input field.
 +-------------+----------------------------------------------------------------------+
 | Rendered as | ``input`` ``hidden`` field                                           |
 +-------------+----------------------------------------------------------------------+
-| Overriden   | - `error_bubbling`_                                                  |
-| options     | - `required`_                                                        |
+| Overriden   | - `compound`_                                                        |
+| options     | - `error_bubbling`_                                                  |
+|             | - `required`_                                                        |
 +-------------+----------------------------------------------------------------------+
 | Inherited   | - `data`_                                                            |
 | options     | - `error_mapping`_                                                   |
@@ -25,6 +26,8 @@ The hidden type represents a hidden input field.
 Overridden Options
 ------------------
 
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
 error_bubbling
 ~~~~~~~~~~~~~~
 

reference/forms/types/integer.rst

@@ -20,6 +20,9 @@ integers. By default, all non-integer values (e.g. 6.78) will round down
 |             | - `scale`_                                                            |
 |             | - `rounding_mode`_                                                    |
 +-------------+-----------------------------------------------------------------------+
+| Overridden  | - `compound`_                                                         |
+| options     |                                                                       |
++-------------+-----------------------------------------------------------------------+
 | Inherited   | - `data`_                                                             |
 | options     | - `disabled`_                                                         |
 |             | - `empty_data`_                                                       |
@@ -74,6 +77,11 @@ on the :class:`Symfony\\Component\\Form\\Extension\\Core\\DataTransformer\\Integ
 * ``IntegerToLocalizedStringTransformer::ROUND_HALF_UP`` Round towards the
   "nearest neighbor". If both neighbors are equidistant, round up.
 
+Overridden Options
+------------------
+
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
 Inherited Options
 -----------------
 

reference/forms/types/language.rst

@@ -24,7 +24,7 @@ you should just use the ``choice`` type directly.
 | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`)           |
 +-------------+------------------------------------------------------------------------+
 | Overridden  | - `choices`_                                                           |
-| Options     |                                                                        |
+| options     |                                                                        |
 +-------------+------------------------------------------------------------------------+
 | Inherited   | from the :doc:`choice </reference/forms/types/choice>` type            |
 | options     |                                                                        |

reference/forms/types/locale.rst

@@ -26,7 +26,7 @@ you should just use the ``choice`` type directly.
 | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`)           |
 +-------------+------------------------------------------------------------------------+
 | Overridden  | - `choices`_                                                           |
-| Options     |                                                                        |
+| options     |                                                                        |
 +-------------+------------------------------------------------------------------------+
 | Inherited   | from the :doc:`choice </reference/forms/types/choice>` type            |
 | options     |                                                                        |

reference/forms/types/money.rst

@@ -19,6 +19,9 @@ how the input and output of the data is handled.
 |             | - `grouping`_                                                       |
 |             | - `scale`_                                                          |
 +-------------+---------------------------------------------------------------------+
+| Overridden  | - `compound`_                                                       |
+| options     |                                                                     |
++-------------+---------------------------------------------------------------------+
 | Inherited   | - `data`_                                                           |
 | options     | - `disabled`_                                                       |
 |             | - `empty_data`_                                                     |
@@ -87,6 +90,11 @@ you can modify this value. You probably won't need to do this unless,
 for example, you want to round to the nearest dollar (set the scale
 to ``0``).
 
+Overridden Options
+------------------
+
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
 Inherited Options
 -----------------
 

reference/forms/types/number.rst

@@ -15,6 +15,9 @@ that you want to use for your number.
 |             | - `scale`_                                                           |
 |             | - `rounding_mode`_                                                   |
 +-------------+----------------------------------------------------------------------+
+| Overridden  | - `compound`_                                                        |
+| options     |                                                                      |
++-------------+----------------------------------------------------------------------+
 | Inherited   | - `data`_                                                            |
 | options     | - `disabled`_                                                        |
 |             | - `empty_data`_                                                      |
@@ -69,6 +72,11 @@ option is a constant on the :class:`Symfony\\Component\\Form\\Extension\\Core\\D
 * ``NumberToLocalizedStringTransformer::ROUND_HALF_UP`` Round towards the
   "nearest neighbor". If both neighbors are equidistant, round up.
 
+Overridden Options
+------------------
+
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
 Inherited Options
 -----------------
 

reference/forms/types/options/compound_type.rst.inc

@@ -0,0 +1,8 @@
+compound
+~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+This option specifies whether the type contains child types or not. This option
+is managed internally for built-in types, so there is no need to configure
+it explicitly.

reference/forms/types/options/data_class_date.rst.inc

@@ -0,0 +1,8 @@
+data_class
+~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+The internal normalized representation of this type is an array, not a ``\DateTime``
+object. Therefore, the ``data_class`` option is initialized to ``null`` to avoid
+the ``FormType`` object from initializing it to ``\DateTime``.

reference/forms/types/password.rst

@@ -11,6 +11,9 @@ The ``password`` field renders an input password text box.
 +-------------+------------------------------------------------------------------------+
 | Options     | - `always_empty`_                                                      |
 +-------------+------------------------------------------------------------------------+
+| Overridden  | - `trim`_                                                              |
+| options     |                                                                        |
++-------------+------------------------------------------------------------------------+
 | Inherited   | - `disabled`_                                                          |
 | options     | - `empty_data`_                                                        |
 |             | - `error_bubbling`_                                                    |
@@ -21,7 +24,6 @@ The ``password`` field renders an input password text box.
 |             | - `max_length`_ (deprecated as of 2.5)                                 |
 |             | - `read_only`_ (deprecated as of 2.8)                                  |
 |             | - `required`_                                                          |
-|             | - `trim`_                                                              |
 +-------------+------------------------------------------------------------------------+
 | Parent type | :doc:`text </reference/forms/types/text>`                              |
 +-------------+------------------------------------------------------------------------+
@@ -44,6 +46,18 @@ Put simply, if for some reason you want to render your password field
 *with* the password value already entered into the box, set this to false
 and submit the form.
 
+Overridden Options
+------------------
+
+trim
+~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+Unlike the rest of form types, the ``password`` type doesn't apply the
+:phpfunction:`trim` function to the value submitted by the user. This ensures that
+the password is merged back onto the underlying object exactly as it was typed
+by the user.
 
 Inherited Options
 -----------------
@@ -76,13 +90,3 @@ The default value is ``''`` (the empty string).
 .. include:: /reference/forms/types/options/read_only.rst.inc
 
 .. include:: /reference/forms/types/options/required.rst.inc
-
-trim
-~~~~
-
-**type**: ``boolean`` **default**: ``false``
-
-If true, the whitespace of the submitted string value will be stripped
-via the :phpfunction:`trim` function when the data is bound. This guarantees
-that if a value is submitted with extra whitespace, it will be removed before
-the value is merged back onto the underlying object.

reference/forms/types/percent.rst

@@ -18,6 +18,9 @@ This field adds a percentage sign "``%``" after the input box.
 | Options     | - `scale`_                                                            |
 |             | - `type`_                                                             |
 +-------------+-----------------------------------------------------------------------+
+| Overridden  | - `compound`_                                                         |
+| options     |                                                                       |
++-------------+-----------------------------------------------------------------------+
 | Inherited   | - `data`_                                                             |
 | options     | - `disabled`_                                                         |
 |             | - `empty_data`_                                                       |
@@ -71,6 +74,11 @@ object. The two "types" handle these two cases:
     The raw value (``55``) is shown to the user and stored on your object.
     Note that this only works for integer values.
 
+Overridden Options
+------------------
+
+.. include:: /reference/forms/types/options/compound_type.rst.inc
+
 Inherited Options
 -----------------