vendor/symfony/options-resolver/Symfony/Component/OptionsResolver/README.md

   1 OptionsResolver Component
   2 =========================
   3
   4 OptionsResolver helps at configuring objects with option arrays.
   5
   6 It supports default values on different levels of your class hierarchy,
   7 option constraints (required vs. optional, allowed values) and lazy options
   8 whose default value depends on the value of another option.
   9
  10 The following example demonstrates a Person class with two required options
  11 "firstName" and "lastName" and two optional options "age" and "gender", where
  12 the default value of "gender" is derived from the passed first name, if
  13 possible, and may only be one of "male" and "female".
  14
  15     use Symfony\Component\OptionsResolver\OptionsResolver;
  16     use Symfony\Component\OptionsResolver\OptionsResolverInterface;
  17     use Symfony\Component\OptionsResolver\Options;
  18
  19     class Person
  20     {
  21         protected $options;
  22
  23         public function __construct(array $options = array())
  24         {
  25             $resolver = new OptionsResolver();
  26             $this->setDefaultOptions($resolver);
  27
  28             $this->options = $resolver->resolve($options);
  29         }
  30
  31         protected function setDefaultOptions(OptionsResolverInterface $resolver)
  32         {
  33             $resolver->setRequired(array(
  34                 'firstName',
  35                 'lastName',
  36             ));
  37
  38             $resolver->setDefaults(array(
  39                 'age' => null,
  40                 'gender' => function (Options $options) {
  41                     if (self::isKnownMaleName($options['firstName'])) {
  42                         return 'male';
  43                     }
  44
  45                     return 'female';
  46                 },
  47             ));
  48
  49             $resolver->setAllowedValues(array(
  50                 'gender' => array('male', 'female'),
  51             ));
  52         }
  53     }
  54
  55 We can now easily instantiate a Person object:
  56
  57     // 'gender' is implicitly set to 'female'
  58     $person = new Person(array(
  59         'firstName' => 'Jane',
  60         'lastName' => 'Doe',
  61     ));
  62
  63 We can also override the default values of the optional options:
  64
  65     $person = new Person(array(
  66         'firstName' => 'Abdullah',
  67         'lastName' => 'Mogashi',
  68         'gender' => 'male',
  69         'age' => 30,
  70     ));
  71
  72 Options can be added or changed in subclasses by overriding the `setDefaultOptions`
  73 method:
  74
  75     use Symfony\Component\OptionsResolver\OptionsResolver;
  76     use Symfony\Component\OptionsResolver\Options;
  77
  78     class Employee extends Person
  79     {
  80         protected function setDefaultOptions(OptionsResolverInterface $resolver)
  81         {
  82             parent::setDefaultOptions($resolver);
  83
  84             $resolver->setRequired(array(
  85                 'birthDate',
  86             ));
  87
  88             $resolver->setDefaults(array(
  89                 // $previousValue contains the default value configured in the
  90                 // parent class
  91                 'age' => function (Options $options, $previousValue) {
  92                     return self::calculateAge($options['birthDate']);
  93                 }
  94             ));
  95         }
  96     }
  97
  98
  99
 100 Resources
 101 ---------
 102
 103 You can run the unit tests with the following command:
 104
 105     $ cd path/to/Symfony/Component/OptionsResolver/
 106     $ composer.phar install --dev
 107     $ phpunit