vendor/symfony/options-resolver/OptionsResolver.php line 243

Open in your IDE?
  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Symfony\Component\OptionsResolver;
  14. use Symfony\Component\OptionsResolver\Exception\AccessException;
  15. use Symfony\Component\OptionsResolver\Exception\InvalidArgumentException;
  16. use Symfony\Component\OptionsResolver\Exception\InvalidOptionsException;
  17. use Symfony\Component\OptionsResolver\Exception\MissingOptionsException;
  18. use Symfony\Component\OptionsResolver\Exception\NoSuchOptionException;
  19. use Symfony\Component\OptionsResolver\Exception\OptionDefinitionException;
  20. use Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException;
  22. /**
  23.  * Validates options and merges them with default values.
  24.  *
  25.  * @author Bernhard Schussek <bschussek@gmail.com>
  26.  * @author Tobias Schultze <http://tobion.de>
  27.  */
  28. class OptionsResolver implements Options
  29. {
  30.     /**
  31.      * The names of all defined options.
  32.      */
  33.     private $defined = [];
  35.     /**
  36.      * The default option values.
  37.      */
  38.     private $defaults = [];
  40.     /**
  41.      * A list of closure for nested options.
  42.      *
  43.      * @var \Closure[][]
  44.      */
  45.     private $nested = [];
  47.     /**
  48.      * The names of required options.
  49.      */
  50.     private $required = [];
  52.     /**
  53.      * The resolved option values.
  54.      */
  55.     private $resolved = [];
  57.     /**
  58.      * A list of normalizer closures.
  59.      *
  60.      * @var \Closure[][]
  61.      */
  62.     private $normalizers = [];
  64.     /**
  65.      * A list of accepted values for each option.
  66.      */
  67.     private $allowedValues = [];
  69.     /**
  70.      * A list of accepted types for each option.
  71.      */
  72.     private $allowedTypes = [];
  74.     /**
  75.      * A list of closures for evaluating lazy options.
  76.      */
  77.     private $lazy = [];
  79.     /**
  80.      * A list of lazy options whose closure is currently being called.
  81.      *
  82.      * This list helps detecting circular dependencies between lazy options.
  83.      */
  84.     private $calling = [];
  86.     /**
  87.      * A list of deprecated options.
  88.      */
  89.     private $deprecated = [];
  91.     /**
  92.      * The list of options provided by the user.
  93.      */
  94.     private $given = [];
  96.     /**
  97.      * Whether the instance is locked for reading.
  98.      *
  99.      * Once locked, the options cannot be changed anymore. This is
  100.      * necessary in order to avoid inconsistencies during the resolving
  101.      * process. If any option is changed after being read, all evaluated
  102.      * lazy options that depend on this option would become invalid.
  103.      */
  104.     private $locked = false;
  106.     private $parentsOptions = [];
  108.     private static $typeAliases = [
  109.         'boolean' => 'bool',
  110.         'integer' => 'int',
  111.         'double' => 'float',
  112.     ];
  114.     /**
  115.      * Sets the default value of a given option.
  116.      *
  117.      * If the default value should be set based on other options, you can pass
  118.      * a closure with the following signature:
  119.      *
  120.      *     function (Options $options) {
  121.      *         // ...
  122.      *     }
  123.      *
  124.      * The closure will be evaluated when {@link resolve()} is called. The
  125.      * closure has access to the resolved values of other options through the
  126.      * passed {@link Options} instance:
  127.      *
  128.      *     function (Options $options) {
  129.      *         if (isset($options['port'])) {
  130.      *             // ...
  131.      *         }
  132.      *     }
  133.      *
  134.      * If you want to access the previously set default value, add a second
  135.      * argument to the closure's signature:
  136.      *
  137.      *     $options->setDefault('name', 'Default Name');
  138.      *
  139.      *     $options->setDefault('name', function (Options $options, $previousValue) {
  140.      *         // 'Default Name' === $previousValue
  141.      *     });
  142.      *
  143.      * This is mostly useful if the configuration of the {@link Options} object
  144.      * is spread across different locations of your code, such as base and
  145.      * sub-classes.
  146.      *
  147.      * If you want to define nested options, you can pass a closure with the
  148.      * following signature:
  149.      *
  150.      *     $options->setDefault('database', function (OptionsResolver $resolver) {
  151.      *         $resolver->setDefined(['dbname', 'host', 'port', 'user', 'pass']);
  152.      *     }
  153.      *
  154.      * To get access to the parent options, add a second argument to the closure's
  155.      * signature:
  156.      *
  157.      *     function (OptionsResolver $resolver, Options $parent) {
  158.      *         // 'default' === $parent['connection']
  159.      *     }
  160.      *
  161.      * @param string $option The name of the option
  162.      * @param mixed  $value  The default value of the option
  163.      *
  164.      * @return $this
  165.      *
  166.      * @throws AccessException If called from a lazy option or normalizer
  167.      */
  168.     public function setDefault(string $option, $value)
  169.     {
  170.         // Setting is not possible once resolving starts, because then lazy
  171.         // options could manipulate the state of the object, leading to
  172.         // inconsistent results.
  173.         if ($this->locked) {
  174.             throw new AccessException('Default values cannot be set from a lazy option or normalizer.');
  175.         }
  177.         // If an option is a closure that should be evaluated lazily, store it
  178.         // in the "lazy" property.
  179.         if ($value instanceof \Closure) {
  180.             $reflClosure = new \ReflectionFunction($value);
  181.             $params = $reflClosure->getParameters();
  183.             if (isset($params[0]) && null !== ($class = $params[0]->getClass()) && Options::class === $class->name) {
  184.                 // Initialize the option if no previous value exists
  185.                 if (!isset($this->defaults[$option])) {
  186.                     $this->defaults[$option] = null;
  187.                 }
  189.                 // Ignore previous lazy options if the closure has no second parameter
  190.                 if (!isset($this->lazy[$option]) || !isset($params[1])) {
  191.                     $this->lazy[$option] = [];
  192.                 }
  194.                 // Store closure for later evaluation
  195.                 $this->lazy[$option][] = $value;
  196.                 $this->defined[$option] = true;
  198.                 // Make sure the option is processed and is not nested anymore
  199.                 unset($this->resolved[$option], $this->nested[$option]);
  201.                 return $this;
  202.             }
  204.             if (isset($params[0]) && null !== ($class = $params[0]->getClass()) && self::class === $class->name && (!isset($params[1]) || (null !== ($class = $params[1]->getClass()) && Options::class === $class->name))) {
  205.                 // Store closure for later evaluation
  206.                 $this->nested[$option][] = $value;
  207.                 $this->defaults[$option] = [];
  208.                 $this->defined[$option] = true;
  210.                 // Make sure the option is processed and is not lazy anymore
  211.                 unset($this->resolved[$option], $this->lazy[$option]);
  213.                 return $this;
  214.             }
  215.         }
  217.         // This option is not lazy nor nested anymore
  218.         unset($this->lazy[$option], $this->nested[$option]);
  220.         // Yet undefined options can be marked as resolved, because we only need
  221.         // to resolve options with lazy closures, normalizers or validation
  222.         // rules, none of which can exist for undefined options
  223.         // If the option was resolved before, update the resolved value
  224.         if (!isset($this->defined[$option]) || \array_key_exists($option, $this->resolved)) {
  225.             $this->resolved[$option] = $value;
  226.         }
  228.         $this->defaults[$option] = $value;
  229.         $this->defined[$option] = true;
  231.         return $this;
  232.     }
  234.     /**
  235.      * Sets a list of default values.
  236.      *
  237.      * @param array $defaults The default values to set
  238.      *
  239.      * @return $this
  240.      *
  241.      * @throws AccessException If called from a lazy option or normalizer
  242.      */
  243.     public function setDefaults(array $defaults)
  244.     {
  245.         foreach ($defaults as $option => $value) {
  246.             $this->setDefault($option, $value);
  247.         }
  249.         return $this;
  250.     }
  252.     /**
  253.      * Returns whether a default value is set for an option.
  254.      *
  255.      * Returns true if {@link setDefault()} was called for this option.
  256.      * An option is also considered set if it was set to null.
  257.      *
  258.      * @param string $option The option name
  259.      *
  260.      * @return bool Whether a default value is set
  261.      */
  262.     public function hasDefault(string $option)
  263.     {
  264.         return \array_key_exists($option, $this->defaults);
  265.     }
  267.     /**
  268.      * Marks one or more options as required.
  269.      *
  270.      * @param string|string[] $optionNames One or more option names
  271.      *
  272.      * @return $this
  273.      *
  274.      * @throws AccessException If called from a lazy option or normalizer
  275.      */
  276.     public function setRequired($optionNames)
  277.     {
  278.         if ($this->locked) {
  279.             throw new AccessException('Options cannot be made required from a lazy option or normalizer.');
  280.         }
  282.         foreach ((array) $optionNames as $option) {
  283.             $this->defined[$option] = true;
  284.             $this->required[$option] = true;
  285.         }
  287.         return $this;
  288.     }
  290.     /**
  291.      * Returns whether an option is required.
  292.      *
  293.      * An option is required if it was passed to {@link setRequired()}.
  294.      *
  295.      * @param string $option The name of the option
  296.      *
  297.      * @return bool Whether the option is required
  298.      */
  299.     public function isRequired(string $option)
  300.     {
  301.         return isset($this->required[$option]);
  302.     }
  304.     /**
  305.      * Returns the names of all required options.
  306.      *
  307.      * @return string[] The names of the required options
  308.      *
  309.      * @see isRequired()
  310.      */
  311.     public function getRequiredOptions()
  312.     {
  313.         return array_keys($this->required);
  314.     }
  316.     /**
  317.      * Returns whether an option is missing a default value.
  318.      *
  319.      * An option is missing if it was passed to {@link setRequired()}, but not
  320.      * to {@link setDefault()}. This option must be passed explicitly to
  321.      * {@link resolve()}, otherwise an exception will be thrown.
  322.      *
  323.      * @param string $option The name of the option
  324.      *
  325.      * @return bool Whether the option is missing
  326.      */
  327.     public function isMissing(string $option)
  328.     {
  329.         return isset($this->required[$option]) && !\array_key_exists($option, $this->defaults);
  330.     }
  332.     /**
  333.      * Returns the names of all options missing a default value.
  334.      *
  335.      * @return string[] The names of the missing options
  336.      *
  337.      * @see isMissing()
  338.      */
  339.     public function getMissingOptions()
  340.     {
  341.         return array_keys(array_diff_key($this->required, $this->defaults));
  342.     }
  344.     /**
  345.      * Defines a valid option name.
  346.      *
  347.      * Defines an option name without setting a default value. The option will
  348.      * be accepted when passed to {@link resolve()}. When not passed, the
  349.      * option will not be included in the resolved options.
  350.      *
  351.      * @param string|string[] $optionNames One or more option names
  352.      *
  353.      * @return $this
  354.      *
  355.      * @throws AccessException If called from a lazy option or normalizer
  356.      */
  357.     public function setDefined($optionNames)
  358.     {
  359.         if ($this->locked) {
  360.             throw new AccessException('Options cannot be defined from a lazy option or normalizer.');
  361.         }
  363.         foreach ((array) $optionNames as $option) {
  364.             $this->defined[$option] = true;
  365.         }
  367.         return $this;
  368.     }
  370.     /**
  371.      * Returns whether an option is defined.
  372.      *
  373.      * Returns true for any option passed to {@link setDefault()},
  374.      * {@link setRequired()} or {@link setDefined()}.
  375.      *
  376.      * @param string $option The option name
  377.      *
  378.      * @return bool Whether the option is defined
  379.      */
  380.     public function isDefined(string $option)
  381.     {
  382.         return isset($this->defined[$option]);
  383.     }
  385.     /**
  386.      * Returns the names of all defined options.
  387.      *
  388.      * @return string[] The names of the defined options
  389.      *
  390.      * @see isDefined()
  391.      */
  392.     public function getDefinedOptions()
  393.     {
  394.         return array_keys($this->defined);
  395.     }
  397.     public function isNested(string $option): bool
  398.     {
  399.         return isset($this->nested[$option]);
  400.     }
  402.     /**
  403.      * Deprecates an option, allowed types or values.
  404.      *
  405.      * Instead of passing the message, you may also pass a closure with the
  406.      * following signature:
  407.      *
  408.      *     function (Options $options, $value): string {
  409.      *         // ...
  410.      *     }
  411.      *
  412.      * The closure receives the value as argument and should return a string.
  413.      * Return an empty string to ignore the option deprecation.
  414.      *
  415.      * The closure is invoked when {@link resolve()} is called. The parameter
  416.      * passed to the closure is the value of the option after validating it
  417.      * and before normalizing it.
  418.      *
  419.      * @param string|\Closure $deprecationMessage
  420.      */
  421.     public function setDeprecated(string $option, $deprecationMessage = 'The option "%name%" is deprecated.'): self
  422.     {
  423.         if ($this->locked) {
  424.             throw new AccessException('Options cannot be deprecated from a lazy option or normalizer.');
  425.         }
  427.         if (!isset($this->defined[$option])) {
  428.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist, defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  429.         }
  431.         if (!\is_string($deprecationMessage) && !$deprecationMessage instanceof \Closure) {
  432.             throw new InvalidArgumentException(sprintf('Invalid type for deprecation message argument, expected string or \Closure, but got "%s".', \gettype($deprecationMessage)));
  433.         }
  435.         // ignore if empty string
  436.         if ('' === $deprecationMessage) {
  437.             return $this;
  438.         }
  440.         $this->deprecated[$option] = $deprecationMessage;
  442.         // Make sure the option is processed
  443.         unset($this->resolved[$option]);
  445.         return $this;
  446.     }
  448.     public function isDeprecated(string $option): bool
  449.     {
  450.         return isset($this->deprecated[$option]);
  451.     }
  453.     /**
  454.      * Sets the normalizer for an option.
  455.      *
  456.      * The normalizer should be a closure with the following signature:
  457.      *
  458.      *     function (Options $options, $value) {
  459.      *         // ...
  460.      *     }
  461.      *
  462.      * The closure is invoked when {@link resolve()} is called. The closure
  463.      * has access to the resolved values of other options through the passed
  464.      * {@link Options} instance.
  465.      *
  466.      * The second parameter passed to the closure is the value of
  467.      * the option.
  468.      *
  469.      * The resolved option value is set to the return value of the closure.
  470.      *
  471.      * @param string   $option     The option name
  472.      * @param \Closure $normalizer The normalizer
  473.      *
  474.      * @return $this
  475.      *
  476.      * @throws UndefinedOptionsException If the option is undefined
  477.      * @throws AccessException           If called from a lazy option or normalizer
  478.      */
  479.     public function setNormalizer(string $option, \Closure $normalizer)
  480.     {
  481.         if ($this->locked) {
  482.             throw new AccessException('Normalizers cannot be set from a lazy option or normalizer.');
  483.         }
  485.         if (!isset($this->defined[$option])) {
  486.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  487.         }
  489.         $this->normalizers[$option] = [$normalizer];
  491.         // Make sure the option is processed
  492.         unset($this->resolved[$option]);
  494.         return $this;
  495.     }
  497.     /**
  498.      * Adds a normalizer for an option.
  499.      *
  500.      * The normalizer should be a closure with the following signature:
  501.      *
  502.      *     function (Options $options, $value): mixed {
  503.      *         // ...
  504.      *     }
  505.      *
  506.      * The closure is invoked when {@link resolve()} is called. The closure
  507.      * has access to the resolved values of other options through the passed
  508.      * {@link Options} instance.
  509.      *
  510.      * The second parameter passed to the closure is the value of
  511.      * the option.
  512.      *
  513.      * The resolved option value is set to the return value of the closure.
  514.      *
  515.      * @param string   $option       The option name
  516.      * @param \Closure $normalizer   The normalizer
  517.      * @param bool     $forcePrepend If set to true, prepend instead of appending
  518.      *
  519.      * @return $this
  520.      *
  521.      * @throws UndefinedOptionsException If the option is undefined
  522.      * @throws AccessException           If called from a lazy option or normalizer
  523.      */
  524.     public function addNormalizer(string $option, \Closure $normalizer, bool $forcePrepend = false): self
  525.     {
  526.         if ($this->locked) {
  527.             throw new AccessException('Normalizers cannot be set from a lazy option or normalizer.');
  528.         }
  530.         if (!isset($this->defined[$option])) {
  531.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  532.         }
  534.         if ($forcePrepend) {
  535.             array_unshift($this->normalizers[$option], $normalizer);
  536.         } else {
  537.             $this->normalizers[$option][] = $normalizer;
  538.         }
  540.         // Make sure the option is processed
  541.         unset($this->resolved[$option]);
  543.         return $this;
  544.     }
  546.     /**
  547.      * Sets allowed values for an option.
  548.      *
  549.      * Instead of passing values, you may also pass a closures with the
  550.      * following signature:
  551.      *
  552.      *     function ($value) {
  553.      *         // return true or false
  554.      *     }
  555.      *
  556.      * The closure receives the value as argument and should return true to
  557.      * accept the value and false to reject the value.
  558.      *
  559.      * @param string $option        The option name
  560.      * @param mixed  $allowedValues One or more acceptable values/closures
  561.      *
  562.      * @return $this
  563.      *
  564.      * @throws UndefinedOptionsException If the option is undefined
  565.      * @throws AccessException           If called from a lazy option or normalizer
  566.      */
  567.     public function setAllowedValues(string $option, $allowedValues)
  568.     {
  569.         if ($this->locked) {
  570.             throw new AccessException('Allowed values cannot be set from a lazy option or normalizer.');
  571.         }
  573.         if (!isset($this->defined[$option])) {
  574.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  575.         }
  577.         $this->allowedValues[$option] = \is_array($allowedValues) ? $allowedValues : [$allowedValues];
  579.         // Make sure the option is processed
  580.         unset($this->resolved[$option]);
  582.         return $this;
  583.     }
  585.     /**
  586.      * Adds allowed values for an option.
  587.      *
  588.      * The values are merged with the allowed values defined previously.
  589.      *
  590.      * Instead of passing values, you may also pass a closures with the
  591.      * following signature:
  592.      *
  593.      *     function ($value) {
  594.      *         // return true or false
  595.      *     }
  596.      *
  597.      * The closure receives the value as argument and should return true to
  598.      * accept the value and false to reject the value.
  599.      *
  600.      * @param string $option        The option name
  601.      * @param mixed  $allowedValues One or more acceptable values/closures
  602.      *
  603.      * @return $this
  604.      *
  605.      * @throws UndefinedOptionsException If the option is undefined
  606.      * @throws AccessException           If called from a lazy option or normalizer
  607.      */
  608.     public function addAllowedValues(string $option, $allowedValues)
  609.     {
  610.         if ($this->locked) {
  611.             throw new AccessException('Allowed values cannot be added from a lazy option or normalizer.');
  612.         }
  614.         if (!isset($this->defined[$option])) {
  615.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  616.         }
  618.         if (!\is_array($allowedValues)) {
  619.             $allowedValues = [$allowedValues];
  620.         }
  622.         if (!isset($this->allowedValues[$option])) {
  623.             $this->allowedValues[$option] = $allowedValues;
  624.         } else {
  625.             $this->allowedValues[$option] = array_merge($this->allowedValues[$option], $allowedValues);
  626.         }
  628.         // Make sure the option is processed
  629.         unset($this->resolved[$option]);
  631.         return $this;
  632.     }
  634.     /**
  635.      * Sets allowed types for an option.
  636.      *
  637.      * Any type for which a corresponding is_<type>() function exists is
  638.      * acceptable. Additionally, fully-qualified class or interface names may
  639.      * be passed.
  640.      *
  641.      * @param string          $option       The option name
  642.      * @param string|string[] $allowedTypes One or more accepted types
  643.      *
  644.      * @return $this
  645.      *
  646.      * @throws UndefinedOptionsException If the option is undefined
  647.      * @throws AccessException           If called from a lazy option or normalizer
  648.      */
  649.     public function setAllowedTypes(string $option, $allowedTypes)
  650.     {
  651.         if ($this->locked) {
  652.             throw new AccessException('Allowed types cannot be set from a lazy option or normalizer.');
  653.         }
  655.         if (!isset($this->defined[$option])) {
  656.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  657.         }
  659.         $this->allowedTypes[$option] = (array) $allowedTypes;
  661.         // Make sure the option is processed
  662.         unset($this->resolved[$option]);
  664.         return $this;
  665.     }
  667.     /**
  668.      * Adds allowed types for an option.
  669.      *
  670.      * The types are merged with the allowed types defined previously.
  671.      *
  672.      * Any type for which a corresponding is_<type>() function exists is
  673.      * acceptable. Additionally, fully-qualified class or interface names may
  674.      * be passed.
  675.      *
  676.      * @param string          $option       The option name
  677.      * @param string|string[] $allowedTypes One or more accepted types
  678.      *
  679.      * @return $this
  680.      *
  681.      * @throws UndefinedOptionsException If the option is undefined
  682.      * @throws AccessException           If called from a lazy option or normalizer
  683.      */
  684.     public function addAllowedTypes(string $option, $allowedTypes)
  685.     {
  686.         if ($this->locked) {
  687.             throw new AccessException('Allowed types cannot be added from a lazy option or normalizer.');
  688.         }
  690.         if (!isset($this->defined[$option])) {
  691.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  692.         }
  694.         if (!isset($this->allowedTypes[$option])) {
  695.             $this->allowedTypes[$option] = (array) $allowedTypes;
  696.         } else {
  697.             $this->allowedTypes[$option] = array_merge($this->allowedTypes[$option], (array) $allowedTypes);
  698.         }
  700.         // Make sure the option is processed
  701.         unset($this->resolved[$option]);
  703.         return $this;
  704.     }
  706.     /**
  707.      * Removes the option with the given name.
  708.      *
  709.      * Undefined options are ignored.
  710.      *
  711.      * @param string|string[] $optionNames One or more option names
  712.      *
  713.      * @return $this
  714.      *
  715.      * @throws AccessException If called from a lazy option or normalizer
  716.      */
  717.     public function remove($optionNames)
  718.     {
  719.         if ($this->locked) {
  720.             throw new AccessException('Options cannot be removed from a lazy option or normalizer.');
  721.         }
  723.         foreach ((array) $optionNames as $option) {
  724.             unset($this->defined[$option], $this->defaults[$option], $this->required[$option], $this->resolved[$option]);
  725.             unset($this->lazy[$option], $this->normalizers[$option], $this->allowedTypes[$option], $this->allowedValues[$option]);
  726.         }
  728.         return $this;
  729.     }
  731.     /**
  732.      * Removes all options.
  733.      *
  734.      * @return $this
  735.      *
  736.      * @throws AccessException If called from a lazy option or normalizer
  737.      */
  738.     public function clear()
  739.     {
  740.         if ($this->locked) {
  741.             throw new AccessException('Options cannot be cleared from a lazy option or normalizer.');
  742.         }
  744.         $this->defined = [];
  745.         $this->defaults = [];
  746.         $this->nested = [];
  747.         $this->required = [];
  748.         $this->resolved = [];
  749.         $this->lazy = [];
  750.         $this->normalizers = [];
  751.         $this->allowedTypes = [];
  752.         $this->allowedValues = [];
  753.         $this->deprecated = [];
  755.         return $this;
  756.     }
  758.     /**
  759.      * Merges options with the default values stored in the container and
  760.      * validates them.
  761.      *
  762.      * Exceptions are thrown if:
  763.      *
  764.      *  - Undefined options are passed;
  765.      *  - Required options are missing;
  766.      *  - Options have invalid types;
  767.      *  - Options have invalid values.
  768.      *
  769.      * @param array $options A map of option names to values
  770.      *
  771.      * @return array The merged and validated options
  772.      *
  773.      * @throws UndefinedOptionsException If an option name is undefined
  774.      * @throws InvalidOptionsException   If an option doesn't fulfill the
  775.      *                                   specified validation rules
  776.      * @throws MissingOptionsException   If a required option is missing
  777.      * @throws OptionDefinitionException If there is a cyclic dependency between
  778.      *                                   lazy options and/or normalizers
  779.      * @throws NoSuchOptionException     If a lazy option reads an unavailable option
  780.      * @throws AccessException           If called from a lazy option or normalizer
  781.      */
  782.     public function resolve(array $options = [])
  783.     {
  784.         if ($this->locked) {
  785.             throw new AccessException('Options cannot be resolved from a lazy option or normalizer.');
  786.         }
  788.         // Allow this method to be called multiple times
  789.         $clone = clone $this;
  791.         // Make sure that no unknown options are passed
  792.         $diff = array_diff_key($options, $clone->defined);
  794.         if (\count($diff) > 0) {
  795.             ksort($clone->defined);
  796.             ksort($diff);
  798.             throw new UndefinedOptionsException(sprintf((\count($diff) > 1 ? 'The options "%s" do not exist.' : 'The option "%s" does not exist.').' Defined options are: "%s".', $this->formatOptions(array_keys($diff)), implode('", "', array_keys($clone->defined))));
  799.         }
  801.         // Override options set by the user
  802.         foreach ($options as $option => $value) {
  803.             $clone->given[$option] = true;
  804.             $clone->defaults[$option] = $value;
  805.             unset($clone->resolved[$option], $clone->lazy[$option]);
  806.         }
  808.         // Check whether any required option is missing
  809.         $diff = array_diff_key($clone->required, $clone->defaults);
  811.         if (\count($diff) > 0) {
  812.             ksort($diff);
  814.             throw new MissingOptionsException(sprintf(\count($diff) > 1 ? 'The required options "%s" are missing.' : 'The required option "%s" is missing.', $this->formatOptions(array_keys($diff))));
  815.         }
  817.         // Lock the container
  818.         $clone->locked = true;
  820.         // Now process the individual options. Use offsetGet(), which resolves
  821.         // the option itself and any options that the option depends on
  822.         foreach ($clone->defaults as $option => $_) {
  823.             $clone->offsetGet($option);
  824.         }
  826.         return $clone->resolved;
  827.     }
  829.     /**
  830.      * Returns the resolved value of an option.
  831.      *
  832.      * @param string $option             The option name
  833.      * @param bool   $triggerDeprecation Whether to trigger the deprecation or not
  834.      *
  835.      * @return mixed The option value
  836.      *
  837.      * @throws AccessException           If accessing this method outside of
  838.      *                                   {@link resolve()}
  839.      * @throws NoSuchOptionException     If the option is not set
  840.      * @throws InvalidOptionsException   If the option doesn't fulfill the
  841.      *                                   specified validation rules
  842.      * @throws OptionDefinitionException If there is a cyclic dependency between
  843.      *                                   lazy options and/or normalizers
  844.      */
  845.     public function offsetGet($option, bool $triggerDeprecation = true)
  846.     {
  847.         if (!$this->locked) {
  848.             throw new AccessException('Array access is only supported within closures of lazy options and normalizers.');
  849.         }
  851.         // Shortcut for resolved options
  852.         if (isset($this->resolved[$option]) || \array_key_exists($option, $this->resolved)) {
  853.             if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || $this->calling) && \is_string($this->deprecated[$option])) {
  854.                 @trigger_error(strtr($this->deprecated[$option], ['%name%' => $option]), E_USER_DEPRECATED);
  855.             }
  857.             return $this->resolved[$option];
  858.         }
  860.         // Check whether the option is set at all
  861.         if (!isset($this->defaults[$option]) && !\array_key_exists($option, $this->defaults)) {
  862.             if (!isset($this->defined[$option])) {
  863.                 throw new NoSuchOptionException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  864.             }
  866.             throw new NoSuchOptionException(sprintf('The optional option "%s" has no value set. You should make sure it is set with "isset" before reading it.', $this->formatOptions([$option])));
  867.         }
  869.         $value = $this->defaults[$option];
  871.         // Resolve the option if it is a nested definition
  872.         if (isset($this->nested[$option])) {
  873.             // If the closure is already being called, we have a cyclic dependency
  874.             if (isset($this->calling[$option])) {
  875.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  876.             }
  878.             if (!\is_array($value)) {
  879.                 throw new InvalidOptionsException(sprintf('The nested option "%s" with value %s is expected to be of type array, but is of type "%s".', $this->formatOptions([$option]), $this->formatValue($value), $this->formatTypeOf($value)));
  880.             }
  882.             // The following section must be protected from cyclic calls.
  883.             $this->calling[$option] = true;
  884.             try {
  885.                 $resolver = new self();
  886.                 $resolver->parentsOptions = $this->parentsOptions;
  887.                 $resolver->parentsOptions[] = $option;
  888.                 foreach ($this->nested[$option] as $closure) {
  889.                     $closure($resolver, $this);
  890.                 }
  891.                 $value = $resolver->resolve($value);
  892.             } finally {
  893.                 unset($this->calling[$option]);
  894.             }
  895.         }
  897.         // Resolve the option if the default value is lazily evaluated
  898.         if (isset($this->lazy[$option])) {
  899.             // If the closure is already being called, we have a cyclic
  900.             // dependency
  901.             if (isset($this->calling[$option])) {
  902.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  903.             }
  905.             // The following section must be protected from cyclic
  906.             // calls. Set $calling for the current $option to detect a cyclic
  907.             // dependency
  908.             // BEGIN
  909.             $this->calling[$option] = true;
  910.             try {
  911.                 foreach ($this->lazy[$option] as $closure) {
  912.                     $value = $closure($this, $value);
  913.                 }
  914.             } finally {
  915.                 unset($this->calling[$option]);
  916.             }
  917.             // END
  918.         }
  920.         // Validate the type of the resolved option
  921.         if (isset($this->allowedTypes[$option])) {
  922.             $valid = true;
  923.             $invalidTypes = [];
  925.             foreach ($this->allowedTypes[$option] as $type) {
  926.                 $type = self::$typeAliases[$type] ?? $type;
  928.                 if ($valid = $this->verifyTypes($type, $value, $invalidTypes)) {
  929.                     break;
  930.                 }
  931.             }
  933.             if (!$valid) {
  934.                 $fmtActualValue = $this->formatValue($value);
  935.                 $fmtAllowedTypes = implode('" or "', $this->allowedTypes[$option]);
  936.                 $fmtProvidedTypes = implode('|', array_keys($invalidTypes));
  937.                 $allowedContainsArrayType = \count(array_filter($this->allowedTypes[$option], static function ($item) {
  938.                     return '[]' === substr(self::$typeAliases[$item] ?? $item, -2);
  939.                 })) > 0;
  941.                 if (\is_array($value) && $allowedContainsArrayType) {
  942.                     throw new InvalidOptionsException(sprintf('The option "%s" with value %s is expected to be of type "%s", but one of the elements is of type "%s".', $this->formatOptions([$option]), $fmtActualValue, $fmtAllowedTypes, $fmtProvidedTypes));
  943.                 }
  945.                 throw new InvalidOptionsException(sprintf('The option "%s" with value %s is expected to be of type "%s", but is of type "%s".', $this->formatOptions([$option]), $fmtActualValue, $fmtAllowedTypes, $fmtProvidedTypes));
  946.             }
  947.         }
  949.         // Validate the value of the resolved option
  950.         if (isset($this->allowedValues[$option])) {
  951.             $success = false;
  952.             $printableAllowedValues = [];
  954.             foreach ($this->allowedValues[$option] as $allowedValue) {
  955.                 if ($allowedValue instanceof \Closure) {
  956.                     if ($allowedValue($value)) {
  957.                         $success = true;
  958.                         break;
  959.                     }
  961.                     // Don't include closures in the exception message
  962.                     continue;
  963.                 }
  965.                 if ($value === $allowedValue) {
  966.                     $success = true;
  967.                     break;
  968.                 }
  970.                 $printableAllowedValues[] = $allowedValue;
  971.             }
  973.             if (!$success) {
  974.                 $message = sprintf(
  975.                     'The option "%s" with value %s is invalid.',
  976.                     $option,
  977.                     $this->formatValue($value)
  978.                 );
  980.                 if (\count($printableAllowedValues) > 0) {
  981.                     $message .= sprintf(
  982.                         ' Accepted values are: %s.',
  983.                         $this->formatValues($printableAllowedValues)
  984.                     );
  985.                 }
  987.                 throw new InvalidOptionsException($message);
  988.             }
  989.         }
  991.         // Check whether the option is deprecated
  992.         // and it is provided by the user or is being called from a lazy evaluation
  993.         if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || ($this->calling && \is_string($this->deprecated[$option])))) {
  994.             $deprecationMessage = $this->deprecated[$option];
  996.             if ($deprecationMessage instanceof \Closure) {
  997.                 // If the closure is already being called, we have a cyclic dependency
  998.                 if (isset($this->calling[$option])) {
  999.                     throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  1000.                 }
  1002.                 $this->calling[$option] = true;
  1003.                 try {
  1004.                     if (!\is_string($deprecationMessage = $deprecationMessage($this, $value))) {
  1005.                         throw new InvalidOptionsException(sprintf('Invalid type for deprecation message, expected string but got "%s", return an empty string to ignore.', \gettype($deprecationMessage)));
  1006.                     }
  1007.                 } finally {
  1008.                     unset($this->calling[$option]);
  1009.                 }
  1010.             }
  1012.             if ('' !== $deprecationMessage) {
  1013.                 @trigger_error(strtr($deprecationMessage, ['%name%' => $option]), E_USER_DEPRECATED);
  1014.             }
  1015.         }
  1017.         // Normalize the validated option
  1018.         if (isset($this->normalizers[$option])) {
  1019.             // If the closure is already being called, we have a cyclic
  1020.             // dependency
  1021.             if (isset($this->calling[$option])) {
  1022.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  1023.             }
  1025.             // The following section must be protected from cyclic
  1026.             // calls. Set $calling for the current $option to detect a cyclic
  1027.             // dependency
  1028.             // BEGIN
  1029.             $this->calling[$option] = true;
  1030.             try {
  1031.                 foreach ($this->normalizers[$option] as $normalizer) {
  1032.                     $value = $normalizer($this, $value);
  1033.                 }
  1034.             } finally {
  1035.                 unset($this->calling[$option]);
  1036.             }
  1037.             // END
  1038.         }
  1040.         // Mark as resolved
  1041.         $this->resolved[$option] = $value;
  1043.         return $value;
  1044.     }
  1046.     private function verifyTypes(string $type, $value, array &$invalidTypes, int $level = 0): bool
  1047.     {
  1048.         if (\is_array($value) && '[]' === substr($type, -2)) {
  1049.             $type = substr($type, 0, -2);
  1050.             $valid = true;
  1052.             foreach ($value as $val) {
  1053.                 if (!$this->verifyTypes($type, $val, $invalidTypes, $level + 1)) {
  1054.                     $valid = false;
  1055.                 }
  1056.             }
  1058.             return $valid;
  1059.         }
  1061.         if (('null' === $type && null === $value) || (\function_exists($func = 'is_'.$type) && $func($value)) || $value instanceof $type) {
  1062.             return true;
  1063.         }
  1065.         if (!$invalidTypes || $level > 0) {
  1066.             $invalidTypes[$this->formatTypeOf($value)] = true;
  1067.         }
  1069.         return false;
  1070.     }
  1072.     /**
  1073.      * Returns whether a resolved option with the given name exists.
  1074.      *
  1075.      * @param string $option The option name
  1076.      *
  1077.      * @return bool Whether the option is set
  1078.      *
  1079.      * @throws AccessException If accessing this method outside of {@link resolve()}
  1080.      *
  1081.      * @see \ArrayAccess::offsetExists()
  1082.      */
  1083.     public function offsetExists($option)
  1084.     {
  1085.         if (!$this->locked) {
  1086.             throw new AccessException('Array access is only supported within closures of lazy options and normalizers.');
  1087.         }
  1089.         return \array_key_exists($option, $this->defaults);
  1090.     }
  1092.     /**
  1093.      * Not supported.
  1094.      *
  1095.      * @throws AccessException
  1096.      */
  1097.     public function offsetSet($option, $value)
  1098.     {
  1099.         throw new AccessException('Setting options via array access is not supported. Use setDefault() instead.');
  1100.     }
  1102.     /**
  1103.      * Not supported.
  1104.      *
  1105.      * @throws AccessException
  1106.      */
  1107.     public function offsetUnset($option)
  1108.     {
  1109.         throw new AccessException('Removing options via array access is not supported. Use remove() instead.');
  1110.     }
  1112.     /**
  1113.      * Returns the number of set options.
  1114.      *
  1115.      * This may be only a subset of the defined options.
  1116.      *
  1117.      * @return int Number of options
  1118.      *
  1119.      * @throws AccessException If accessing this method outside of {@link resolve()}
  1120.      *
  1121.      * @see \Countable::count()
  1122.      */
  1123.     public function count()
  1124.     {
  1125.         if (!$this->locked) {
  1126.             throw new AccessException('Counting is only supported within closures of lazy options and normalizers.');
  1127.         }
  1129.         return \count($this->defaults);
  1130.     }
  1132.     /**
  1133.      * Returns a string representation of the type of the value.
  1134.      *
  1135.      * @param mixed $value The value to return the type of
  1136.      *
  1137.      * @return string The type of the value
  1138.      */
  1139.     private function formatTypeOf($value): string
  1140.     {
  1141.         return \is_object($value) ? \get_class($value) : \gettype($value);
  1142.     }
  1144.     /**
  1145.      * Returns a string representation of the value.
  1146.      *
  1147.      * This method returns the equivalent PHP tokens for most scalar types
  1148.      * (i.e. "false" for false, "1" for 1 etc.). Strings are always wrapped
  1149.      * in double quotes (").
  1150.      *
  1151.      * @param mixed $value The value to format as string
  1152.      */
  1153.     private function formatValue($value): string
  1154.     {
  1155.         if (\is_object($value)) {
  1156.             return \get_class($value);
  1157.         }
  1159.         if (\is_array($value)) {
  1160.             return 'array';
  1161.         }
  1163.         if (\is_string($value)) {
  1164.             return '"'.$value.'"';
  1165.         }
  1167.         if (\is_resource($value)) {
  1168.             return 'resource';
  1169.         }
  1171.         if (null === $value) {
  1172.             return 'null';
  1173.         }
  1175.         if (false === $value) {
  1176.             return 'false';
  1177.         }
  1179.         if (true === $value) {
  1180.             return 'true';
  1181.         }
  1183.         return (string) $value;
  1184.     }
  1186.     /**
  1187.      * Returns a string representation of a list of values.
  1188.      *
  1189.      * Each of the values is converted to a string using
  1190.      * {@link formatValue()}. The values are then concatenated with commas.
  1191.      *
  1192.      * @see formatValue()
  1193.      */
  1194.     private function formatValues(array $values): string
  1195.     {
  1196.         foreach ($values as $key => $value) {
  1197.             $values[$key] = $this->formatValue($value);
  1198.         }
  1200.         return implode(', ', $values);
  1201.     }
  1203.     private function formatOptions(array $options): string
  1204.     {
  1205.         if ($this->parentsOptions) {
  1206.             $prefix = array_shift($this->parentsOptions);
  1207.             if ($this->parentsOptions) {
  1208.                 $prefix .= sprintf('[%s]', implode('][', $this->parentsOptions));
  1209.             }
  1211.             $options = array_map(static function (string $option) use ($prefix): string {
  1212.                 return sprintf('%s[%s]', $prefix, $option);
  1213.             }, $options);
  1214.         }
  1216.         return implode('", "', $options);
  1217.     }
  1218. }