Merge branch '4.2'

* 4.2:
  [OptionsResolver] Documenting nested options feature
  Add missing imports in Data Mappers article
  fix code style
  Complete code example for \"Adding validation\" part

Author: javiereguiluz

components/options_resolver.rst

@@ -634,6 +634,101 @@ let you find out which options are defined::
         }
     }
 
+Nested Options
+~~~~~~~~~~~~~~
+
+.. versionadded:: 4.2
+    The support of nested options was introduced in Symfony 4.2.
+
+Suppose you have an option named ``spool`` which has two sub-options ``type``
+and ``path``. Instead of defining it as a simple array of values, you can pass a
+closure as the default value of the ``spool`` option with a
+:class:`Symfony\\Component\\OptionsResolver\\OptionsResolver` argument. Based on
+this instance, you can define the options under ``spool`` and its desired
+default value::
+
+    class Mailer
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefault('spool', function (OptionsResolver $spoolResolver) {
+                $spoolResolver->setDefaults(array(
+                    'type' => 'file',
+                    'path' => '/path/to/spool',
+                ));
+                $spoolResolver->setAllowedValues('type', array('file', 'memory'));
+                $spoolResolver->setAllowedTypes('path', 'string');
+            });
+        }
+
+        public function sendMail($from, $to)
+        {
+            if ('memory' === $this->options['spool']['type']) {
+                // ...
+            }
+        }
+    }
+
+    $mailer = new Mailer(array(
+        'spool' => array(
+            'type' => 'memory',
+        ),
+    ));
+
+Nested options also support required options, validation (type, value) and
+normalization of their values. If the default value of a nested option depends
+on another option defined in the parent level, add a second ``Options`` argument
+to the closure to access to them::
+
+    class Mailer
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefault('sandbox', false);
+            $resolver->setDefault('spool', function (OptionsResolver $spoolResolver, Options $parent) {
+                $spoolResolver->setDefaults(array(
+                    'type' => $parent['sandbox'] ? 'memory' : 'file',
+                    // ...
+                ));
+            });
+        }
+    }
+
+.. caution::
+
+    The arguments of the closure must be type hinted as ``OptionsResolver`` and
+    ``Options`` respectively. Otherwise, the closure itself is considered as the
+    default value of the option.
+
+In same way, parent options can access to the nested options as normal arrays::
+
+    class Mailer
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefault('spool', function (OptionsResolver $spoolResolver) {
+                $spoolResolver->setDefaults(array(
+                    'type' => 'file',
+                    // ...
+                ));
+            });
+            $resolver->setDefault('profiling', function (Options $options) {
+                return 'file' === $options['spool']['type'];
+            });
+        }
+    }
+
+.. note::
+
+    The fact that an option is defined as nested means that you must pass
+    an array of values to resolve it at runtime.
+
 Deprecating the Option
 ~~~~~~~~~~~~~~~~~~~~~~
 

form/data_mappers.rst

@@ -149,7 +149,10 @@ method to configure the data mapper::
     namespace App\Form\Type;
 
     use App\Form\DataMapper\ColorMapper;
+    use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\Extension\Core\Type\IntegerType;
+    use Symfony\Component\Form\FormBuilderInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     final class ColorType extends AbstractType
     {

form/without_class.rst

@@ -82,18 +82,22 @@ but here's a short example::
     use Symfony\Component\Validator\Constraints\Length;
     use Symfony\Component\Validator\Constraints\NotBlank;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
 
-    $builder
-       ->add('firstName', TextType::class, array(
-           'constraints' => new Length(array('min' => 3)),
-       ))
-       ->add('lastName', TextType::class, array(
-           'constraints' => array(
-               new NotBlank(),
-               new Length(array('min' => 3)),
-           ),
-       ))
-    ;
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder
+           ->add('firstName', TextType::class, array(
+               'constraints' => new Length(array('min' => 3)),
+           ))
+           ->add('lastName', TextType::class, array(
+               'constraints' => array(
+                   new NotBlank(),
+                   new Length(array('min' => 3)),
+               ),
+           ))
+        ;
+    }
 
 .. tip::
 

validation/custom_constraint.rst

@@ -66,7 +66,7 @@ The validator class is also simple, and only has one required method ``validate(
         public function validate($value, Constraint $constraint)
         {
             if (!$constraint instanceof ContainsAlphanumeric) {
-               throw new UnexpectedTypeException($constraint, ContainsAlphanumeric::class);
+                throw new UnexpectedTypeException($constraint, ContainsAlphanumeric::class);
             }
             
             // custom constraints should ignore null and empty values to allow