Merge branch '3.4' into 4.2

* 3.4:
  Added the docs for the \"groups\" constraint option
  fixed paragraph about which versionadded directives will be removed

Author: javiereguiluz

contributing/community/review-comments.rst

@@ -91,15 +91,15 @@ Don't use hyperbole ("always", "never", "endlessly", "nothing", "worst", "horrib
 **Don't:** *"I don't like how you wrote this code"* - there is no clear explanation why you
 don't like how it's written.
 
-**Better:** *"I find it hard to read this code as there is many nested if statements, can you make it more
-readable? By encapsulating some of its details or maybe adding some comments to explain the overall logic."* -
+**Better:** *"I find it hard to read this code as there are many nested if statements, can you make it more
+readable? By encapsulating some of the details or maybe adding some comments to explain the overall logic."* -
 You explain why you find the code hard to read *and* give some suggestions for improvement.
 
 If a piece of code is in fact wrong, explain why:
 
 * "This code doesn't comply with Symfony's CS rules. Please see [...] for details."
 
-* "Symfony 3 still uses PHP 5 and doesn't allow the usage scalar type-hints."
+* "Symfony 3 still uses PHP 5 and doesn't allow the usage of scalar type-hints."
 
 * "I think the code is less readable now." - careful here, be sure explain why you think
   the code is less readable, and maybe give some suggestions?

contributing/documentation/format.rst

@@ -173,32 +173,30 @@ New Features or Behavior Changes
 
 If you're documenting a brand new feature or a change that's been made in
 Symfony, you should precede your description of the change with a
-``.. versionadded:: 2.X`` directive and a short description:
+``.. versionadded:: 3.x`` directive and a short description:
 
 .. code-block:: rst
 
-    .. versionadded:: 2.7
+    .. versionadded:: 3.4
 
-        The ``askHiddenResponse()`` method was introduced in Symfony 2.7.
-
-    You can also ask a question and hide the response. This is particularly [...]
+        The special ``!`` template prefix was introduced in Symfony 3.4.
 
 If you're documenting a behavior change, it may be helpful to *briefly* describe
 how the behavior has changed:
 
 .. code-block:: rst
 
-    .. versionadded:: 2.7
+    .. versionadded:: 3.4
 
-        The ``include()`` function is a new Twig feature that's available in
-        Symfony 2.7. Prior, the ``{% include %}`` tag was used.
+        Support for annotation routing without an external bundle was added in
+        Symfony 3.4. Prior, you needed to install the SensioFrameworkExtraBundle.
 
-Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc),
+Whenever a new major version of Symfony is released (e.g. 3.0, 4.0, etc),
 a new branch of the documentation is created from the ``master`` branch.
 At this point, all the ``versionadded`` tags for Symfony versions that have
-reached end-of-maintenance will be removed. For example, if Symfony 2.5 were
-released today, and 2.2 had recently reached its end-of-maintenance, the 2.2
-``versionadded`` tags would be removed from the new ``2.5`` branch.
+a lower major version will be removed. For example, if Symfony 4.0 were
+released today, 3.0 to 3.4 ``versionadded`` tags would be removed from the new
+``4.0`` branch.
 
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx-doc.org/

reference/constraints/All.rst

@@ -8,6 +8,7 @@ you to apply a collection of constraints to each element of the array.
 | Applies to     | :ref:`property or method <validation-property-target>`            |
 +----------------+-------------------------------------------------------------------+
 | Options        | - `constraints`_                                                  |
+|                | - `groups`_                                                       |
 |                | - `payload`_                                                      |
 +----------------+-------------------------------------------------------------------+
 | Class          | :class:`Symfony\\Component\\Validator\\Constraints\\All`          |
@@ -109,4 +110,6 @@ constraints
 This required option is the array of validation constraints that you want
 to apply to each element of the underlying array.
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 .. include:: /reference/constraints/_payload-option.rst.inc

reference/constraints/Bic.rst

@@ -9,7 +9,8 @@ check that the BIC is associated with a given IBAN.
 +----------------+-----------------------------------------------------------------------+
 | Applies to     | :ref:`property or method <validation-property-target>`                |
 +----------------+-----------------------------------------------------------------------+
-| Options        | - `message`_                                                          |
+| Options        | - `groups`_                                                           |
+|                | - `message`_                                                          |
 |                | - `payload`_                                                          |
 |                | - `iban`_                                                             |
 |                | - `ibanMessage`_                                                      |
@@ -89,6 +90,8 @@ will contain a Business Identifier Code (BIC).
 Available Options
 -----------------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 

reference/constraints/Blank.rst

@@ -16,7 +16,8 @@ But be careful as ``NotBlank`` is *not* strictly the opposite of ``Blank``.
 +----------------+---------------------------------------------------------------------+
 | Applies to     | :ref:`property or method <validation-property-target>`              |
 +----------------+---------------------------------------------------------------------+
-| Options        | - `message`_                                                        |
+| Options        | - `groups`_                                                         |
+|                | - `message`_                                                        |
 |                | - `payload`_                                                        |
 +----------------+---------------------------------------------------------------------+
 | Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Blank`          |
@@ -89,6 +90,8 @@ of an ``Author`` class were blank, you could do the following:
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 

reference/constraints/Callback.rst

@@ -21,6 +21,7 @@ can do anything, including creating and assigning validation errors.
 | Applies to     | :ref:`class <validation-class-target>`                                 |
 +----------------+------------------------------------------------------------------------+
 | Options        | - :ref:`callback <callback-option>`                                    |
+|                | - `groups`_                                                            |
 |                | - `payload`_                                                           |
 +----------------+------------------------------------------------------------------------+
 | Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Callback`          |
@@ -275,4 +276,6 @@ Static or closure callbacks receive the validated object as the first argument
 and the :class:`Symfony\\Component\\Validator\\Context\\ExecutionContextInterface`
 instance as the second argument.
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 .. include:: /reference/constraints/_payload-option.rst.inc

reference/constraints/CardScheme.rst

@@ -8,7 +8,8 @@ a payment through a payment gateway.
 +----------------+--------------------------------------------------------------------------+
 | Applies to     | :ref:`property or method <validation-property-target>`                   |
 +----------------+--------------------------------------------------------------------------+
-| Options        | - `schemes`_                                                             |
+| Options        | - `groups`_                                                              |
+|                | - `schemes`_                                                             |
 |                | - `message`_                                                             |
 |                | - `payload`_                                                             |
 +----------------+--------------------------------------------------------------------------+
@@ -101,6 +102,8 @@ on an object that will contain a credit card number.
 Available Options
 -----------------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 schemes
 ~~~~~~~
 

reference/constraints/Choice.rst

@@ -10,6 +10,7 @@ an array of items is one of those valid choices.
 +----------------+----------------------------------------------------------------------+
 | Options        | - `choices`_                                                         |
 |                | - `callback`_                                                        |
+|                | - `groups`_                                                          |
 |                | - `multiple`_                                                        |
 |                | - `min`_                                                             |
 |                | - `max`_                                                             |
@@ -295,6 +296,8 @@ This is a callback method that can be used instead of the `choices`_ option
 to return the choices array. See
 `Supplying the Choices with a Callback Function`_ for details on its usage.
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 multiple
 ~~~~~~~~
 

reference/constraints/Collection.rst

@@ -14,10 +14,11 @@ and that extra keys are not present.
 +----------------+--------------------------------------------------------------------------+
 | Applies to     | :ref:`property or method <validation-property-target>`                   |
 +----------------+--------------------------------------------------------------------------+
-| Options        | - `fields`_                                                              |
-|                | - `allowExtraFields`_                                                    |
-|                | - `extraFieldsMessage`_                                                  |
+| Options        | - `allowExtraFields`_                                                    |
 |                | - `allowMissingFields`_                                                  |
+|                | - `extraFieldsMessage`_                                                  |
+|                | - `fields`_                                                              |
+|                | - `groups`_                                                              |
 |                | - `missingFieldsMessage`_                                                |
 |                | - `payload`_                                                             |
 +----------------+--------------------------------------------------------------------------+
@@ -289,15 +290,6 @@ the ``NotBlank`` constraint will still be applied (since it is wrapped in
 Options
 -------
 
-fields
-~~~~~~
-
-**type**: ``array`` [:ref:`default option <validation-default-option>`]
-
-This option is required and is an associative array defining all of the
-keys in the collection and, for each key, exactly which validator(s) should
-be executed against that element of the collection.
-
 allowExtraFields
 ~~~~~~~~~~~~~~~~
 
@@ -307,6 +299,16 @@ If this option is set to ``false`` and the underlying collection contains
 one or more elements that are not included in the `fields`_ option, a validation
 error will be returned. If set to ``true``, extra fields are ok.
 
+allowMissingFields
+~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: false
+
+If this option is set to ``false`` and one or more fields from the `fields`_
+option are not present in the underlying collection, a validation error
+will be returned. If set to ``true``, it's ok if some fields in the `fields`_
+option are not present in the underlying collection.
+
 extraFieldsMessage
 ~~~~~~~~~~~~~~~~~~
 
@@ -323,15 +325,16 @@ You can use the following parameters in this message:
 | ``{{ field }}``  | The key of the extra field detected            |
 +------------------+------------------------------------------------+
 
-allowMissingFields
-~~~~~~~~~~~~~~~~~~
+fields
+~~~~~~
 
-**type**: ``boolean`` **default**: false
+**type**: ``array`` [:ref:`default option <validation-default-option>`]
 
-If this option is set to ``false`` and one or more fields from the `fields`_
-option are not present in the underlying collection, a validation error
-will be returned. If set to ``true``, it's ok if some fields in the `fields`_
-option are not present in the underlying collection.
+This option is required and is an associative array defining all of the
+keys in the collection and, for each key, exactly which validator(s) should
+be executed against that element of the collection.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 missingFieldsMessage
 ~~~~~~~~~~~~~~~~~~~~

reference/constraints/Count.rst

@@ -13,6 +13,7 @@ Countable) element count is *between* some minimum and maximum value.
 |                | - `maxMessage`_                                                     |
 |                | - `exactMessage`_                                                   |
 |                | - `payload`_                                                        |
+|                | - `groups`_                                                         |
 +----------------+---------------------------------------------------------------------+
 | Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Count`          |
 +----------------+---------------------------------------------------------------------+
@@ -103,6 +104,8 @@ you might add the following:
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 min
 ~~~