Merge branch '4.1' into 4.2

* 4.1:
  [symfony#10704] fix the line length
  [symfony#10259] minor tweaks
  Unexpected PHP behavior
  [symfony#10514] remove trailing whitespaces
  Added description for the "validation_groups" option
  Don't recommend requiring with Composer
  Tip about using stopwatch to show in profiler page

Author: xabbuh

components/phpunit_bridge.rst

@@ -540,6 +540,27 @@ namespaces in the ``phpunit.xml`` file, as done for example in the
             </listener>
         </listeners>
     </phpunit>
+    
+Under the hood, a PHPUnit listener injects the mocked functions in the tested
+classes' namespace. In order to work as expected, the listener has to run before
+the tested class ever runs. By default, the mocked functions are created when the
+annotation are found and the corresponding tests are run. Depending on how your
+tests are constructed, this might be too late. In this case, you will need to declare
+the namespaces of the tested classes in your phpunit.xml.dist
+
+.. code-block:: xml
+
+    <!-- phpunit.xml.dist -->
+    <!-- ... -->
+    <listeners>
+        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
+                <arguments>
+                    <array>
+                        <element key="time-sensitive"><string>Acme\MyClassTest</string></element>
+                    </array>
+                </arguments>
+            </listener>
+    </listeners>
 
 Modified PHPUnit script
 -----------------------

components/stopwatch.rst

@@ -61,6 +61,12 @@ You can also provide a category name to an event::
 You can consider categories as a way of tagging events. For example, the
 Symfony Profiler tool uses categories to nicely color-code different events.
 
+.. tip::
+
+    When you want to show events in the Symfony profiler, autowire
+    ``Symfony\Component\Stopwatch\Stopwatch`` into your service. Each category
+    is shown on a separate line.
+
 Periods
 -------
 

reference/forms/types/form.rst

@@ -32,6 +32,7 @@ on all types for which ``FormType`` is the parent.
 |           | - `property_path`_                                                 |
 |           | - `required`_                                                      |
 |           | - `trim`_                                                          |
+|           | - `validation_groups`_                                             |
 +-----------+--------------------------------------------------------------------+
 | Inherited | - `attr`_                                                          |
 | options   | - `auto_initialize`_                                               |
@@ -136,6 +137,8 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/trim.rst.inc
 
+.. include:: /reference/forms/types/options/validation_groups.rst.inc
+
 Inherited Options
 -----------------
 

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

@@ -0,0 +1,82 @@
+validation_groups
+~~~~~~~~~~~~~~~~~
+
+**type**: ``array``, ``string``, ``callable``, :class:`Symfony\\Component\\Validator\\Constraints\\GroupSequence` or ``null`` **default**: ``null``
+
+This option is only valid on the root form and is used to specify which
+groups will be used by the validator.
+
+For ``null`` the validator will just use the ``Default`` group.
+
+If you specify the groups as an array or string they will be used by the
+validator as they are::
+
+    public function configureOptions(OptionsResolver $resolver)
+    {
+        $resolver->setDefaults(array(
+            'validation_groups' => 'Registration',
+        ));
+    }
+
+This is equivalent to passing the group as array::
+
+    'validation_groups' => array('Registration'),
+
+The form's data will be :doc:`validated against all given groups </form/validation_groups>`.
+
+If the validation groups depend on the form's data a callable may be passed to
+the option. Symfony will then pass the form when calling it::
+
+    use Symfony\Component\Form\FormInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+
+    // ...
+    public function configureOptions(OptionsResolver $resolver)
+    {
+        $resolver->setDefaults(array(
+            'validation_groups' => function (FormInterface $form) {
+                $entity = $form->getData();
+
+                return $entity->isUser() ? array('User') : array('Company');
+            },
+        ));
+    }
+
+.. seealso::
+
+    You can read more about this in :doc:`/form/data_based_validation`.
+
+.. note::
+
+    When your form contains multiple submit buttons, you can change the
+    validation group depending on :doc:`which button is used</form/button_based_validation>`
+    to submit the form.
+
+    If you need advanced logic to determine the validation groups have
+    a look at :doc:`/form/validation_group_service_resolver`.
+
+In some cases, you want to validate your groups step by step. To do this, you
+can pass a :class:`Symfony\\Component\\Validator\\Constraints\\GroupSequence`
+to this option. This enables you to validate against multiple groups,
+like when you pass multiple groups in an array, but with the difference that
+a group is only validated if the previous groups pass without errors.
+Here's an example::
+
+    use Symfony\Component\Validator\Constraints\GroupSequence;
+    use Symfony\Component\Form\AbstractType;
+    // ...
+
+    class MyType extends AbstractType
+    {
+        // ...
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefaults([
+                'validation_groups' => new GroupSequence(['First', 'Second']),
+            ]);
+        }
+    }
+
+.. seealso::
+
+    Read the article :doc:`/validation/sequence_provider` to find out more about this.

setup.rst

@@ -116,17 +116,8 @@ Checking for Security Vulnerabilities
 -------------------------------------
 
 Symfony provides a utility called the "Security Checker" to check whether your
-project's dependencies contain any known security vulnerability. Run this
-command to install it in your application:
-
-.. code-block:: terminal
-
-    $ cd my-project/
-    $ composer require sensiolabs/security-checker --dev
-
-From now on, this utility will be run automatically whenever you install or
-update any dependency in the application. If a dependency contains a vulnerability,
-you'll see a clear message.
+project's dependencies contain any known security vulnerability. Check out
+the integration instructions for `the Security Checker`_ to set it up.
 
 The Symfony Demo application
 ----------------------------
@@ -162,5 +153,6 @@ Go Deeper with Setup
 
 .. _`Stellar Development with Symfony`: http://symfonycasts.com/screencast/symfony
 .. _`Composer`: https://getcomposer.org/
+.. _`the Security Checker`: https://github.com/sensiolabs/security-checker#integration
 .. _`The Symfony Demo application`: https://github.com/symfony/demo
 .. _`symfony/symfony-demo`: https://github.com/symfony/demo