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

Summary

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

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

  $connexionResolver = $resolver->setNested('connexion', array(
      'host' => 'localhost',
      'port' => 80,
  );
  
  $connexionResolver->setRequired('user');
  $connexionResolver->setDefault('password', function (Options $connexion) {
      return isset($nested['user']) ? '' : null;
  });
  $connexionResolver->setDefault('secure', false);
  $connexionResolver->setNormalizer('secure', function (Options $connexion, $secure) {
      return 443 === $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 class
  parent::configureOptions($resolver);
  
  $resolver->setDefault('user', $user);
  $connexionResolver = $resolver->setDefault(
      'connexion', function (Options $options, $previousDefaultConnexion) {
          if ($options['user'] instanceof UserInterface and '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 ? throw BadMethodCallException ? what do you think ?

• 9e4e02a fixes [OptionsResolver] array of instance allowed type #15524. Handle extra options resolving and addAllowed*ForAll rules with constant flags

  • add Options::NONE constant,
  • add Options::ALL constant, matches defined and extra options,
  • add Options::DEFINED constant,
  • add Options::NESTED constant,
  • add Options::EXTRA constant, matches any undefined options, helps dealing with "anonymous" options (using a numerical index)
  • add OptionsResolver::allowedValuesForAll a private array to validate all options even undefined but not root of nested options as they must always be an array,
  • add OptionsResolver::allowedTypesForAll a private array to validate all options (as previous),
  • add OptionsResolver::resolveUndefined a private bool to allow extra options resolving,
  • add OptionsResolver::addAllowedValuesForAll($options, $allowedValues, $replace = false, $nested = Options::ALL), first argument may be an array of options names or any flag constant except Options::NONE, if a root name of nested options is passed as/among first argument the method will be recursive because the fourth argument default is Options::ALL, prevent it by passing Options::NONE instead,
  • add OptionsResolver::addAllowedTypesForAll($options, $allowedTypes, $replace, $nested), same as previous, note that passing Options::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, pass true as third argument to override previous allowed types,
  • add OptionsResolver::setPrototypes((string|string[]) $types, (mixed) $values, $options = Options::EXTRA), sets resolveUndefined to true and validate any extra options with the any given type with its corresponding allowed values,
  • add OptionsResolver::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) {
          return preg_match($regex, $email);
      });

  The difference is that in the second case implicitly the flag Options::EXTRA is passed so previous defaults will not be validate by prototypes rules, if that's not what you want pass Options::ALL as third argument.
  Note that setNested() returns the nested OptionsResolver 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

  • add NestedOptions class which extends OptionsResolver,
  • add NestedOptions::root the parent OptionsResolver instance,
  • add NestedOptions::rootName the root option name,
  • add NestedOptions::resolve() overrides to throw an exception is parent OptionsResolver instance is not locked,
  • add OptionsResolver::isLocked() internal public method to check from NestedOptions if it can be resolved.

Work in Progress (RFC)

• add OptionsResolver::setExtraNormalizer(function (Options $options, $extraName, $extraValue) { ... }) to normalize any undefined options, basically a shortcut for the currently supported setNormalizer(Options::Extra, callable) but with handling of $extraName
• add a OptionsResolver::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.