feature #27291 [OptionsResolver] Added support for nesting options definition (yceruto)

This PR was merged into the 4.2-dev branch.

Discussion
----------

[OptionsResolver] Added support for nesting options definition

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #4833
| License       | MIT
| Doc PR        | symfony/symfony-docs#9995

I'd like to propose an alternative to #27251 and #18134 with a different approach.

It would allow you to create a nested options system with required options, validation (type, value),
normalization and more.

<details>
 <summary><strong>Short documentation</strong></summary>

**To define a nested option, you can pass a closure as the default value of the option with an `OptionsResolver` argument:**
```php
$resolver
    ->defaults([
        'connection' => 'default',
        'database' => function (OptionsResolver $resolver) {
            $resolver
                ->setRequired(['dbname', 'host', ...])
                ->setDefaults([
                    'driver' => 'pdo_sqlite',
                    'port' => function (Options $options) {
                        return 'pdo_mysql' === $options['driver'] ? 3306 : null,
                    },
                    'logging' => true,
                ])
                ->setAllowedValues('driver', ['pdo_sqlite', 'pdo_mysql'])
                ->setAllowedTypes('port', 'int')
                ->setAllowedTypes('logging', 'bool')
                // ...
        },
    ]);

$resolver->resolve(array(
    'database' => array(
        'dbname' => 'demo',
        'host' => 'localhost',
        'driver' => 'pdo_mysql',
    ),
));

// returns: array(
//    'connection' => 'default',
//    'database' => array(
//        'dbname' => 'demo',
//        'host' => 'localhost',
//        'driver' => 'pdo_mysql',
//        'port' => 3306,
//        'logging' => true,
//    ),
//)
```
Based on this instance, you can define the options under ``database`` and its desired default
value.

**If the default value of a child option depend on another option defined in parent level,
adds a second ``Options`` argument to the closure:**
```php
$resolver
    ->defaults([
        'profiling' => false,
        'database' => function (OptionsResolver $resolver, Options $parent) {
            $resolver
                ->setDefault('logging', $parent['profiling'])
                ->setAllowedTypes('logging', 'bool');
        },
    ])
;
```
**Access to nested options from lazy or normalize functions in parent level:**
```php
$resolver
    ->defaults([
        'version' => function (Options $options) {
            return $options['database']['server_version'];
        },
        'database' => function (OptionsResolver $resolver) {
            $resolver
                ->setDefault('server_version', 3.15)
                ->setAllowedTypes('server_version', 'numeric')
                // ...
        },
    ])
;
```
As condition, for nested options you must to pass an array of values to resolve it on runtime, otherwise an exception will be thrown:
```php
$resolver->resolve(); // OK
$resolver->resolve(['database' => []]); // OK
$resolver->resolve(['database' => null); // KO (Exception!)
```
</details>

---

Demo app https://github.com/yceruto/nested-optionsresolver-demo

Commits
-------

d04e40be5a Added support for nested options definition

Author: fabpot

CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 4.2.0
 -----
 
+ * added support for nested options definition
  * added `setDeprecated` and `isDeprecated` methods
 
 3.4.0

OptionsResolver.php

@@ -37,6 +37,13 @@ class OptionsResolver implements Options
      */
     private $defaults = array();
 
+    /**
+     * A list of closure for nested options.
+     *
+     * @var \Closure[][]
+     */
+    private $nested = array();
+
     /**
      * The names of required options.
      */
@@ -130,6 +137,20 @@ class OptionsResolver implements Options
      * is spread across different locations of your code, such as base and
      * sub-classes.
      *
+     * If you want to define nested options, you can pass a closure with the
+     * following signature:
+     *
+     *     $options->setDefault('database', function (OptionsResolver $resolver) {
+     *         $resolver->setDefined(array('dbname', 'host', 'port', 'user', 'pass'));
+     *     }
+     *
+     * To get access to the parent options, add a second argument to the closure's
+     * signature:
+     *
+     *     function (OptionsResolver $resolver, Options $parent) {
+     *         // 'default' === $parent['connection']
+     *     }
+     *
      * @param string $option The name of the option
      * @param mixed  $value  The default value of the option
      *
@@ -167,15 +188,27 @@ public function setDefault($option, $value)
                 $this->lazy[$option][] = $value;
                 $this->defined[$option] = true;
 
-                // Make sure the option is processed
-                unset($this->resolved[$option]);
+                // Make sure the option is processed and is not nested anymore
+                unset($this->resolved[$option], $this->nested[$option]);
+
+                return $this;
+            }
+
+            if (isset($params[0]) && null !== ($class = $params[0]->getClass()) && self::class === $class->name && (!isset($params[1]) || (null !== ($class = $params[1]->getClass()) && Options::class === $class->name))) {
+                // Store closure for later evaluation
+                $this->nested[$option][] = $value;
+                $this->defaults[$option] = array();
+                $this->defined[$option] = true;
+
+                // Make sure the option is processed and is not lazy anymore
+                unset($this->resolved[$option], $this->lazy[$option]);
 
                 return $this;
             }
         }
 
-        // This option is not lazy anymore
-        unset($this->lazy[$option]);
+        // This option is not lazy nor nested anymore
+        unset($this->lazy[$option], $this->nested[$option]);
 
         // Yet undefined options can be marked as resolved, because we only need
         // to resolve options with lazy closures, normalizers or validation
@@ -354,6 +387,11 @@ public function getDefinedOptions()
         return array_keys($this->defined);
     }
 
+    public function isNested(string $option): bool
+    {
+        return isset($this->nested[$option]);
+    }
+
     /**
      * Deprecates an option, allowed types or values.
      *
@@ -649,6 +687,7 @@ public function clear()
 
         $this->defined = array();
         $this->defaults = array();
+        $this->nested = array();
         $this->required = array();
         $this->resolved = array();
         $this->lazy = array();
@@ -767,6 +806,32 @@ public function offsetGet($option)
 
         $value = $this->defaults[$option];
 
+        // Resolve the option if it is a nested definition
+        if (isset($this->nested[$option])) {
+            // If the closure is already being called, we have a cyclic dependency
+            if (isset($this->calling[$option])) {
+                throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', implode('", "', array_keys($this->calling))));
+            }
+
+            if (!\is_array($value)) {
+                throw new InvalidOptionsException(sprintf('The nested option "%s" with value %s is expected to be of type array, but is of type "%s".', $option, $this->formatValue($value), $this->formatTypeOf($value, 'array')));
+            }
+
+            // The following section must be protected from cyclic calls.
+            // BEGIN
+            $this->calling[$option] = true;
+            try {
+                $resolver = new self();
+                foreach ($this->nested[$option] as $closure) {
+                    $closure($resolver, $this);
+                }
+                $value = $resolver->resolve($value);
+            } finally {
+                unset($this->calling[$option]);
+            }
+            // END
+        }
+
         // Resolve the option if the default value is lazily evaluated
         if (isset($this->lazy[$option])) {
             // If the closure is already being called, we have a cyclic