From 32591735b90dd40323193b9b48ea7fc43474e113 Mon Sep 17 00:00:00 2001 From: Yonel Ceruto Date: Mon, 2 Jul 2018 18:40:03 -0400 Subject: [PATCH 1/4] Documenting nested options feature for OptionsResolver component --- components/options_resolver.rst | 99 +++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/components/options_resolver.rst b/components/options_resolver.rst index 0d7d3360359..9927259100d 100644 --- 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 ~~~~~~~~~~~~~~~~~~~~~~ From 4412e91c8b27bd7cbf32b2bf3fb9f51f4bee0f9a Mon Sep 17 00:00:00 2001 From: Yonel Ceruto Date: Wed, 10 Oct 2018 10:17:29 -0400 Subject: [PATCH 2/4] fix typos --- components/options_resolver.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/components/options_resolver.rst b/components/options_resolver.rst index 9927259100d..89ab1991849 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -634,15 +634,15 @@ let you find out which options are defined:: } } -Nested option +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` +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:: @@ -706,7 +706,7 @@ adds a second ``Options`` argument to the closure:: 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:: +In same way, parent options can access the child option as follows:: // ... class Mailer @@ -730,8 +730,8 @@ In same way, parent options can access to the child option as follows:: .. 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. + 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 ~~~~~~~~~~~~~~~~~~~~~~ From 44e1a3d26df7f06fe24d587d74766752b2bc5c1e Mon Sep 17 00:00:00 2001 From: Yonel Ceruto Date: Fri, 12 Oct 2018 14:55:28 -0400 Subject: [PATCH 3/4] Removing some // ... :) --- components/options_resolver.rst | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/components/options_resolver.rst b/components/options_resolver.rst index 89ab1991849..d0025659d48 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -646,13 +646,12 @@ a closure as the default value of the ``spool`` option with a :class:`Symfony\\C 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', @@ -683,20 +682,18 @@ 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', // ... )); - // ... }); } } @@ -708,19 +705,17 @@ adds a second ``Options`` argument to the closure:: In same way, parent options can access 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']; From 5abcf6a25db9d04d7ba281d99c458bc5a870b8b1 Mon Sep 17 00:00:00 2001 From: Yonel Ceruto Date: Thu, 29 Nov 2018 08:21:02 -0500 Subject: [PATCH 4/4] Minor tweaks --- components/options_resolver.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/components/options_resolver.rst b/components/options_resolver.rst index d0025659d48..32005552063 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -640,7 +640,7 @@ 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`` +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 @@ -676,11 +676,11 @@ value:: ), )); -It allows you to create a nested options system with required options, validation (type, value), -normalization and more. +Also you can define required options, validation (type, value) and normalization of these +nested options. If the default value of a child option depend on another option defined in parent level, -adds a second ``Options`` argument to the closure:: +adds a second ``Options`` argument to the closure for access to them:: class Mailer { @@ -703,7 +703,7 @@ adds a second ``Options`` argument to the closure:: 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 the child option as follows:: +In same way, parent options can access to the child option as normal array:: class Mailer {