From bf5d9d351847ca79a587876160dfd093677ea8ec Mon Sep 17 00:00:00 2001 From: Elias Van Ootegem Date: Fri, 18 Dec 2015 17:55:18 +0000 Subject: [PATCH 1/3] Document typed arrays in optionsresolver --- components/options_resolver.rst | 37 +++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/components/options_resolver.rst b/components/options_resolver.rst index 1ed2347b4d8..58f3f5718e1 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -340,6 +340,43 @@ is thrown:: In sub-classes, you can use :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::addAllowedTypes` to add additional allowed types without erasing the ones already set. +You can specify an array of a specific type as an allowed option. The expected type is +validated in the same way as before (``is_()`` or an ``instanceof`` check). +Only for an array, this is done recursively. If you expect an option to be an array of +``DateTime`` instances or a numeric array, you can specify this as follows:: + + // ... + class Mailer + { + // ... + public function configureOptions(OptionsResolver $resolver) + { + // ... + $resolver->setAllowedTypes('dates', 'DateTime[]'); + $resolver->setAllowedTypes('ports', 'int[]'); + } + } + +Because the OptionsResolver will validate typed arrays recurively, it is possible to +resolve multi-dimensional arrays, too:: + + // ... + class Mailer + { + // ... + public function configureOptions(OptionsResolver $resolver) + { + // ... + //allowed type is a 2D array of string values + $resolver->setAllowedTypes('hosts', 'string[][]'); + } + } + +.. versionadded:: 3.1 + Before Symfony 3.1, the allowed types had to be scalar values, qualified classes + or interfaces. The only way to ensure the values of an array were of the right type + was to use a normalizer. + Value Validation ~~~~~~~~~~~~~~~~ From 318e199d0333f262eed5f9d03a0045b80ccdb377 Mon Sep 17 00:00:00 2001 From: Elias Van Ootegem Date: Mon, 21 Dec 2015 09:54:27 +0000 Subject: [PATCH 2/3] Fix typo --- components/options_resolver.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/options_resolver.rst b/components/options_resolver.rst index 58f3f5718e1..e19991e2b1f 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -357,7 +357,7 @@ Only for an array, this is done recursively. If you expect an option to be an ar } } -Because the OptionsResolver will validate typed arrays recurively, it is possible to +Because the OptionsResolver will validate typed arrays recursively, it is possible to resolve multi-dimensional arrays, too:: // ... From cb12592c5f52010c6aecf8ed4a1fd1c89f9c2e03 Mon Sep 17 00:00:00 2001 From: Wouter J Date: Sun, 31 Dec 2017 13:58:48 +0100 Subject: [PATCH 3/3] Merged new example in older example, removing some text --- components/options_resolver.rst | 56 ++++++++++----------------------- 1 file changed, 16 insertions(+), 40 deletions(-) diff --git a/components/options_resolver.rst b/components/options_resolver.rst index e19991e2b1f..54fa38829ba 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -317,14 +317,27 @@ correctly. To validate the types of the options, call public function configureOptions(OptionsResolver $resolver) { // ... + + // specify one allowed type $resolver->setAllowedTypes('host', 'string'); + + // specify multiple allowed types $resolver->setAllowedTypes('port', array('null', 'int')); + + // check all items in an array recursively for a type + $resolver->setAllowedTypes('dates', 'DateTime[]'); + $resolver->setAllowedtypes('ports', 'int[]'); } } -For each option, you can define either just one type or an array of acceptable -types. You can pass any type for which an ``is_()`` function is defined -in PHP. Additionally, you may pass fully qualified class or interface names. +You can pass any type for which an ``is_()`` function is defined in PHP. +You may also pass fully qualified class or interface names (which is checked +using ``instanceof``). Additionally, you can validate all items in an array +recursively by suffixing the type with ``[]``. + +.. versionadded:: 3.4 + Validating types of array items recursively was introduced in Symfony 3.4. + Prior to Symfony 3.4, only scalar values could be validated. If you pass an invalid option now, an :class:`Symfony\\Component\\OptionsResolver\\Exception\\InvalidOptionsException` @@ -340,43 +353,6 @@ is thrown:: In sub-classes, you can use :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::addAllowedTypes` to add additional allowed types without erasing the ones already set. -You can specify an array of a specific type as an allowed option. The expected type is -validated in the same way as before (``is_()`` or an ``instanceof`` check). -Only for an array, this is done recursively. If you expect an option to be an array of -``DateTime`` instances or a numeric array, you can specify this as follows:: - - // ... - class Mailer - { - // ... - public function configureOptions(OptionsResolver $resolver) - { - // ... - $resolver->setAllowedTypes('dates', 'DateTime[]'); - $resolver->setAllowedTypes('ports', 'int[]'); - } - } - -Because the OptionsResolver will validate typed arrays recursively, it is possible to -resolve multi-dimensional arrays, too:: - - // ... - class Mailer - { - // ... - public function configureOptions(OptionsResolver $resolver) - { - // ... - //allowed type is a 2D array of string values - $resolver->setAllowedTypes('hosts', 'string[][]'); - } - } - -.. versionadded:: 3.1 - Before Symfony 3.1, the allowed types had to be scalar values, qualified classes - or interfaces. The only way to ensure the values of an array were of the right type - was to use a normalizer. - Value Validation ~~~~~~~~~~~~~~~~