Documenting nested options feature for OptionsResolver component

symfony · yceruto · Jul 2, 2018 · Oct 10, 2018 · Oct 12, 2018 · Nov 29, 2018
commit 32591735b90dd40323193b9b48ea7fc43474e113
diff --git a/components/options_resolver.rst b/components/options_resolver.rst
@@ -634,6 +634,105 @@ let you find out which options are defined::
        }
    }

+Nested option
+~~~~~~~~~~~~~
+
+.. versionadded:: 4.2
+    This feature was introduced in Symfony 4.2.
+
+Suppose you want an option named ``spool`` which has two sub-options ``type``
+and ``path``. Instead of define it as a simple array of values, you can pass
+a closure as the default value of the ``spool`` option with an :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',
+        ),
+    ));
+
+It allows you to create a nested options system with required options, validation (type, value),
+normalization and more.
+
+If the default value of a child option depend on another option defined in parent level,
+adds a second ``Options`` argument to the closure::
+
+    // ...
+    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 child option as follows::
+
+    // ...
+    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 to pass
+    an array of values to resolve it on runtime.
+
 Deprecating the Option
 ~~~~~~~~~~~~~~~~~~~~~~