• Gather feedback
• Address a doc PR
• Update CHANGELOG
• Add a lot of tests :)

Summary

• c2944acfixes[OptionsResolver] Support nested options #4833. Handle nested options resolving

  • addOptionsResolver::nested a private array of nestedOptionsResolver instances by root names,
  • addOptionsResolver::setNested($option, array $defaults) defines an option as a new self and returns the nestedOptionsResolver instance,
  • addOptionsResolver::isNested($option) returns whether an option name is a root name for a nestedOptionsResolver instance,
  • addOptionsResolver::getNested() an array of root names representing nestedOptionsResolver instances.

  $connexionResolver =$resolver->setNested('connexion',array('host' =>'localhost','port' =>80,);$connexionResolver->setRequired('user');$connexionResolver->setDefault('password',function (Options$connexion) {returnisset($nested['user']) ?'' :null;});$connexionResolver->setDefault('secure',false);$connexionResolver->setNormalizer('secure',function (Options$connexion,$secure) {return443 ===$nested['port'] ?:$secure;});$connexionResolver->setAllowedTypes('port','int');$connexionResolver->setAllowedTypes('user','string');$resolver->setRequired('connexion');$resolver->setNormalizer('connexion',function (Options$options,$resolvedConnexion) {if ('localhost' ===$resolvedConnexion['host']) {$resolvedConnexion['host'] =$option['param'];    }return$resolvedConnexion;});// In a sub classparent::configureOptions($resolver);$resolver->setDefault('user',$user);$connexionResolver =$resolver->setDefault('connexion',function (Options$options,$previousDefaultConnexion) {if ($options['user']instanceof UserInterfaceand'localhost' !==$previousDefaultConnexion['host'])$connexion['user'] =$options['user']->getUsername();        });$options =$resolver->resolve($array);

  *Allowed* methods are not supported with root name of nested options since they always have to be an array, so:

• f2ad947 trigger warning ? throwBadMethodCallException ? what do you think ?

• 9e4e02afixes[OptionsResolver] array of instance allowed type #15524. Handle extra options resolving andaddAllowed*ForAll rules with constant flags

  • addOptions::NONE constant,
  • addOptions::ALL constant, matches defined and extra options,
  • addOptions::DEFINED constant,
  • addOptions::NESTED constant,
  • addOptions::EXTRA constant, matches any undefined options, helps dealing with "anonymous" options (using a numerical index)
  • addOptionsResolver::allowedValuesForAll a private array to validate all options even undefined but not root of nested options as they must always be an array,
  • addOptionsResolver::allowedTypesForAll a private array to validate all options (as previous),
  • addOptionsResolver::resolveUndefined a privatebool to allow extra options resolving,
  • addOptionsResolver::addAllowedValuesForAll($options, $allowedValues, $replace = false, $nested = Options::ALL), first argument may be an array of options names or any flag constant exceptOptions::NONE, if a root name of nested options is passed as/among first argument the method will be recursive because the fourth argument default isOptions::ALL, prevent it by passingOptions::NONE instead,
  • addOptionsResolver::addAllowedTypesForAll($options, $allowedTypes, $replace, $nested), same as previous, note that passingOptions::ALL as first argument will not apply to root of nested options as they must always be arrays and on contrary will apply on extra options, passtrue as third argument to override previous allowed types,
  • addOptionsResolver::setPrototypes((string|string[]) $types, (mixed) $values, $options = Options::EXTRA), setsresolveUndefined totrue and validate any extra options with the any given type with its corresponding allowed values,
  • addOptionsResolver::allowExtraOptions($allow = true)

  $resolver->setNested('attachments',array($attachments))    ->allowExtraOptions()    ->addAllowedTypesForAll(Options::ALL,'\Swift_Attachment');// Another way by implicitly allowing extra options:$resolver->setNested('emails')    ->setPrototypes('string',function ($email)use ($regex) {returnpreg_match($regex,$email);    });

  The difference is that in the second case implicitly the flagOptions::EXTRA is passed so previous defaults will not be validate by prototypes rules, if that's not what you want passOptions::ALL as third argument.
  Note thatsetNested() returns the nestedOptionsResolver instance in this examples, you could call these methods on the$resolver as well but this not the same:

  // Any undefined global options can only be strings$resolver    ->allowExtraOptions()    ->addAllowTypesForAll(Options::EXTRA,'string',true, Options::NONE);

• ccd5ce1 Harden dependency of nested options with an internal class

  • addNestedOptions class which extendsOptionsResolver,
  • addNestedOptions::root the parentOptionsResolver instance,
  • addNestedOptions::rootName the root option name,
  • addNestedOptions::resolve() overrides to throw an exception is parentOptionsResolver instance is not locked,
  • addOptionsResolver::isLocked() internal public method to check fromNestedOptions if it can be resolved.

Work in Progress (RFC)

• addOptionsResolver::setExtraNormalizer(function (Options $options, $extraName, $extraValue) { ... }) to normalize any undefined options, basically a shortcut for the currently supportedsetNormalizer(Options::Extra, callable) but with handling of$extraName
• add aOptionsResolver::prototypes private array holding allowed values by allowed types to validate extra options.
• be more strict on NestedOptions array type and indexing when setting defaults. Currently the implementation does not distinguish nested defaults using a numerical index instead of names, which may cause problem when overriding them or to properly map validation/normalization.