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

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.     private const VALIDATION_FUNCTIONS = [
  31.         'bool' => 'is_bool',
  32.         'boolean' => 'is_bool',
  33.         'int' => 'is_int',
  34.         'integer' => 'is_int',
  35.         'long' => 'is_int',
  36.         'float' => 'is_float',
  37.         'double' => 'is_float',
  38.         'real' => 'is_float',
  39.         'numeric' => 'is_numeric',
  40.         'string' => 'is_string',
  41.         'scalar' => 'is_scalar',
  42.         'array' => 'is_array',
  43.         'iterable' => 'is_iterable',
  44.         'countable' => 'is_countable',
  45.         'callable' => 'is_callable',
  46.         'object' => 'is_object',
  47.         'resource' => 'is_resource',
  48.     ];
  50.     /**
  51.      * The names of all defined options.
  52.      */
  53.     private $defined = [];
  55.     /**
  56.      * The default option values.
  57.      */
  58.     private $defaults = [];
  60.     /**
  61.      * A list of closure for nested options.
  62.      *
  63.      * @var \Closure[][]
  64.      */
  65.     private $nested = [];
  67.     /**
  68.      * The names of required options.
  69.      */
  70.     private $required = [];
  72.     /**
  73.      * The resolved option values.
  74.      */
  75.     private $resolved = [];
  77.     /**
  78.      * A list of normalizer closures.
  79.      *
  80.      * @var \Closure[][]
  81.      */
  82.     private $normalizers = [];
  84.     /**
  85.      * A list of accepted values for each option.
  86.      */
  87.     private $allowedValues = [];
  89.     /**
  90.      * A list of accepted types for each option.
  91.      */
  92.     private $allowedTypes = [];
  94.     /**
  95.      * A list of info messages for each option.
  96.      */
  97.     private $info = [];
  99.     /**
  100.      * A list of closures for evaluating lazy options.
  101.      */
  102.     private $lazy = [];
  104.     /**
  105.      * A list of lazy options whose closure is currently being called.
  106.      *
  107.      * This list helps detecting circular dependencies between lazy options.
  108.      */
  109.     private $calling = [];
  111.     /**
  112.      * A list of deprecated options.
  113.      */
  114.     private $deprecated = [];
  116.     /**
  117.      * The list of options provided by the user.
  118.      */
  119.     private $given = [];
  121.     /**
  122.      * Whether the instance is locked for reading.
  123.      *
  124.      * Once locked, the options cannot be changed anymore. This is
  125.      * necessary in order to avoid inconsistencies during the resolving
  126.      * process. If any option is changed after being read, all evaluated
  127.      * lazy options that depend on this option would become invalid.
  128.      */
  129.     private $locked = false;
  131.     private $parentsOptions = [];
  133.     /**
  134.      * Sets the default value of a given option.
  135.      *
  136.      * If the default value should be set based on other options, you can pass
  137.      * a closure with the following signature:
  138.      *
  139.      *     function (Options $options) {
  140.      *         // ...
  141.      *     }
  142.      *
  143.      * The closure will be evaluated when {@link resolve()} is called. The
  144.      * closure has access to the resolved values of other options through the
  145.      * passed {@link Options} instance:
  146.      *
  147.      *     function (Options $options) {
  148.      *         if (isset($options['port'])) {
  149.      *             // ...
  150.      *         }
  151.      *     }
  152.      *
  153.      * If you want to access the previously set default value, add a second
  154.      * argument to the closure's signature:
  155.      *
  156.      *     $options->setDefault('name', 'Default Name');
  157.      *
  158.      *     $options->setDefault('name', function (Options $options, $previousValue) {
  159.      *         // 'Default Name' === $previousValue
  160.      *     });
  161.      *
  162.      * This is mostly useful if the configuration of the {@link Options} object
  163.      * is spread across different locations of your code, such as base and
  164.      * sub-classes.
  165.      *
  166.      * If you want to define nested options, you can pass a closure with the
  167.      * following signature:
  168.      *
  169.      *     $options->setDefault('database', function (OptionsResolver $resolver) {
  170.      *         $resolver->setDefined(['dbname', 'host', 'port', 'user', 'pass']);
  171.      *     }
  172.      *
  173.      * To get access to the parent options, add a second argument to the closure's
  174.      * signature:
  175.      *
  176.      *     function (OptionsResolver $resolver, Options $parent) {
  177.      *         // 'default' === $parent['connection']
  178.      *     }
  179.      *
  180.      * @param string $option The name of the option
  181.      * @param mixed  $value  The default value of the option
  182.      *
  183.      * @return $this
  184.      *
  185.      * @throws AccessException If called from a lazy option or normalizer
  186.      */
  187.     public function setDefault(string $option, $value)
  188.     {
  189.         // Setting is not possible once resolving starts, because then lazy
  190.         // options could manipulate the state of the object, leading to
  191.         // inconsistent results.
  192.         if ($this->locked) {
  193.             throw new AccessException('Default values cannot be set from a lazy option or normalizer.');
  194.         }
  196.         // If an option is a closure that should be evaluated lazily, store it
  197.         // in the "lazy" property.
  198.         if ($value instanceof \Closure) {
  199.             $reflClosure = new \ReflectionFunction($value);
  200.             $params = $reflClosure->getParameters();
  202.             if (isset($params[0]) && Options::class === $this->getParameterClassName($params[0])) {
  203.                 // Initialize the option if no previous value exists
  204.                 if (!isset($this->defaults[$option])) {
  205.                     $this->defaults[$option] = null;
  206.                 }
  208.                 // Ignore previous lazy options if the closure has no second parameter
  209.                 if (!isset($this->lazy[$option]) || !isset($params[1])) {
  210.                     $this->lazy[$option] = [];
  211.                 }
  213.                 // Store closure for later evaluation
  214.                 $this->lazy[$option][] = $value;
  215.                 $this->defined[$option] = true;
  217.                 // Make sure the option is processed and is not nested anymore
  218.                 unset($this->resolved[$option], $this->nested[$option]);
  220.                 return $this;
  221.             }
  223.             if (isset($params[0]) && null !== ($type = $params[0]->getType()) && self::class === $type->getName() && (!isset($params[1]) || (($type = $params[1]->getType()) instanceof \ReflectionNamedType && Options::class === $type->getName()))) {
  224.                 // Store closure for later evaluation
  225.                 $this->nested[$option][] = $value;
  226.                 $this->defaults[$option] = [];
  227.                 $this->defined[$option] = true;
  229.                 // Make sure the option is processed and is not lazy anymore
  230.                 unset($this->resolved[$option], $this->lazy[$option]);
  232.                 return $this;
  233.             }
  234.         }
  236.         // This option is not lazy nor nested anymore
  237.         unset($this->lazy[$option], $this->nested[$option]);
  239.         // Yet undefined options can be marked as resolved, because we only need
  240.         // to resolve options with lazy closures, normalizers or validation
  241.         // rules, none of which can exist for undefined options
  242.         // If the option was resolved before, update the resolved value
  243.         if (!isset($this->defined[$option]) || \array_key_exists($option, $this->resolved)) {
  244.             $this->resolved[$option] = $value;
  245.         }
  247.         $this->defaults[$option] = $value;
  248.         $this->defined[$option] = true;
  250.         return $this;
  251.     }
  253.     /**
  254.      * Sets a list of default values.
  255.      *
  256.      * @param array $defaults The default values to set
  257.      *
  258.      * @return $this
  259.      *
  260.      * @throws AccessException If called from a lazy option or normalizer
  261.      */
  262.     public function setDefaults(array $defaults)
  263.     {
  264.         foreach ($defaults as $option => $value) {
  265.             $this->setDefault($option, $value);
  266.         }
  268.         return $this;
  269.     }
  271.     /**
  272.      * Returns whether a default value is set for an option.
  273.      *
  274.      * Returns true if {@link setDefault()} was called for this option.
  275.      * An option is also considered set if it was set to null.
  276.      *
  277.      * @param string $option The option name
  278.      *
  279.      * @return bool Whether a default value is set
  280.      */
  281.     public function hasDefault(string $option)
  282.     {
  283.         return \array_key_exists($option, $this->defaults);
  284.     }
  286.     /**
  287.      * Marks one or more options as required.
  288.      *
  289.      * @param string|string[] $optionNames One or more option names
  290.      *
  291.      * @return $this
  292.      *
  293.      * @throws AccessException If called from a lazy option or normalizer
  294.      */
  295.     public function setRequired($optionNames)
  296.     {
  297.         if ($this->locked) {
  298.             throw new AccessException('Options cannot be made required from a lazy option or normalizer.');
  299.         }
  301.         foreach ((array) $optionNames as $option) {
  302.             $this->defined[$option] = true;
  303.             $this->required[$option] = true;
  304.         }
  306.         return $this;
  307.     }
  309.     /**
  310.      * Returns whether an option is required.
  311.      *
  312.      * An option is required if it was passed to {@link setRequired()}.
  313.      *
  314.      * @param string $option The name of the option
  315.      *
  316.      * @return bool Whether the option is required
  317.      */
  318.     public function isRequired(string $option)
  319.     {
  320.         return isset($this->required[$option]);
  321.     }
  323.     /**
  324.      * Returns the names of all required options.
  325.      *
  326.      * @return string[] The names of the required options
  327.      *
  328.      * @see isRequired()
  329.      */
  330.     public function getRequiredOptions()
  331.     {
  332.         return array_keys($this->required);
  333.     }
  335.     /**
  336.      * Returns whether an option is missing a default value.
  337.      *
  338.      * An option is missing if it was passed to {@link setRequired()}, but not
  339.      * to {@link setDefault()}. This option must be passed explicitly to
  340.      * {@link resolve()}, otherwise an exception will be thrown.
  341.      *
  342.      * @param string $option The name of the option
  343.      *
  344.      * @return bool Whether the option is missing
  345.      */
  346.     public function isMissing(string $option)
  347.     {
  348.         return isset($this->required[$option]) && !\array_key_exists($option, $this->defaults);
  349.     }
  351.     /**
  352.      * Returns the names of all options missing a default value.
  353.      *
  354.      * @return string[] The names of the missing options
  355.      *
  356.      * @see isMissing()
  357.      */
  358.     public function getMissingOptions()
  359.     {
  360.         return array_keys(array_diff_key($this->required, $this->defaults));
  361.     }
  363.     /**
  364.      * Defines a valid option name.
  365.      *
  366.      * Defines an option name without setting a default value. The option will
  367.      * be accepted when passed to {@link resolve()}. When not passed, the
  368.      * option will not be included in the resolved options.
  369.      *
  370.      * @param string|string[] $optionNames One or more option names
  371.      *
  372.      * @return $this
  373.      *
  374.      * @throws AccessException If called from a lazy option or normalizer
  375.      */
  376.     public function setDefined($optionNames)
  377.     {
  378.         if ($this->locked) {
  379.             throw new AccessException('Options cannot be defined from a lazy option or normalizer.');
  380.         }
  382.         foreach ((array) $optionNames as $option) {
  383.             $this->defined[$option] = true;
  384.         }
  386.         return $this;
  387.     }
  389.     /**
  390.      * Returns whether an option is defined.
  391.      *
  392.      * Returns true for any option passed to {@link setDefault()},
  393.      * {@link setRequired()} or {@link setDefined()}.
  394.      *
  395.      * @param string $option The option name
  396.      *
  397.      * @return bool Whether the option is defined
  398.      */
  399.     public function isDefined(string $option)
  400.     {
  401.         return isset($this->defined[$option]);
  402.     }
  404.     /**
  405.      * Returns the names of all defined options.
  406.      *
  407.      * @return string[] The names of the defined options
  408.      *
  409.      * @see isDefined()
  410.      */
  411.     public function getDefinedOptions()
  412.     {
  413.         return array_keys($this->defined);
  414.     }
  416.     public function isNested(string $option): bool
  417.     {
  418.         return isset($this->nested[$option]);
  419.     }
  421.     /**
  422.      * Deprecates an option, allowed types or values.
  423.      *
  424.      * Instead of passing the message, you may also pass a closure with the
  425.      * following signature:
  426.      *
  427.      *     function (Options $options, $value): string {
  428.      *         // ...
  429.      *     }
  430.      *
  431.      * The closure receives the value as argument and should return a string.
  432.      * Return an empty string to ignore the option deprecation.
  433.      *
  434.      * The closure is invoked when {@link resolve()} is called. The parameter
  435.      * passed to the closure is the value of the option after validating it
  436.      * and before normalizing it.
  437.      *
  438.      * @param string          $package The name of the composer package that is triggering the deprecation
  439.      * @param string          $version The version of the package that introduced the deprecation
  440.      * @param string|\Closure $message The deprecation message to use
  441.      */
  442.     public function setDeprecated(string $option/*, string $package, string $version, $message = 'The option "%name%" is deprecated.' */): self
  443.     {
  444.         if ($this->locked) {
  445.             throw new AccessException('Options cannot be deprecated from a lazy option or normalizer.');
  446.         }
  448.         if (!isset($this->defined[$option])) {
  449.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist, defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  450.         }
  452.         $args = \func_get_args();
  454.         if (\func_num_args() < 3) {
  455.             trigger_deprecation('symfony/options-resolver', '5.1', 'The signature of method "%s()" requires 2 new arguments: "string $package, string $version", not defining them is deprecated.', __METHOD__);
  457.             $message = $args[1] ?? 'The option "%name%" is deprecated.';
  458.             $package = $version = '';
  459.         } else {
  460.             $package = $args[1];
  461.             $version = $args[2];
  462.             $message = $args[3] ?? 'The option "%name%" is deprecated.';
  463.         }
  465.         if (!\is_string($message) && !$message instanceof \Closure) {
  466.             throw new InvalidArgumentException(sprintf('Invalid type for deprecation message argument, expected string or \Closure, but got "%s".', get_debug_type($message)));
  467.         }
  469.         // ignore if empty string
  470.         if ('' === $message) {
  471.             return $this;
  472.         }
  474.         $this->deprecated[$option] = [
  475.             'package' => $package,
  476.             'version' => $version,
  477.             'message' => $message,
  478.         ];
  480.         // Make sure the option is processed
  481.         unset($this->resolved[$option]);
  483.         return $this;
  484.     }
  486.     public function isDeprecated(string $option): bool
  487.     {
  488.         return isset($this->deprecated[$option]);
  489.     }
  491.     /**
  492.      * Sets the normalizer for an option.
  493.      *
  494.      * The normalizer should be a closure with the following signature:
  495.      *
  496.      *     function (Options $options, $value) {
  497.      *         // ...
  498.      *     }
  499.      *
  500.      * The closure is invoked when {@link resolve()} is called. The closure
  501.      * has access to the resolved values of other options through the passed
  502.      * {@link Options} instance.
  503.      *
  504.      * The second parameter passed to the closure is the value of
  505.      * the option.
  506.      *
  507.      * The resolved option value is set to the return value of the closure.
  508.      *
  509.      * @param string   $option     The option name
  510.      * @param \Closure $normalizer The normalizer
  511.      *
  512.      * @return $this
  513.      *
  514.      * @throws UndefinedOptionsException If the option is undefined
  515.      * @throws AccessException           If called from a lazy option or normalizer
  516.      */
  517.     public function setNormalizer(string $option, \Closure $normalizer)
  518.     {
  519.         if ($this->locked) {
  520.             throw new AccessException('Normalizers cannot be set from a lazy option or normalizer.');
  521.         }
  523.         if (!isset($this->defined[$option])) {
  524.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  525.         }
  527.         $this->normalizers[$option] = [$normalizer];
  529.         // Make sure the option is processed
  530.         unset($this->resolved[$option]);
  532.         return $this;
  533.     }
  535.     /**
  536.      * Adds a normalizer for an option.
  537.      *
  538.      * The normalizer should be a closure with the following signature:
  539.      *
  540.      *     function (Options $options, $value): mixed {
  541.      *         // ...
  542.      *     }
  543.      *
  544.      * The closure is invoked when {@link resolve()} is called. The closure
  545.      * has access to the resolved values of other options through the passed
  546.      * {@link Options} instance.
  547.      *
  548.      * The second parameter passed to the closure is the value of
  549.      * the option.
  550.      *
  551.      * The resolved option value is set to the return value of the closure.
  552.      *
  553.      * @param string   $option       The option name
  554.      * @param \Closure $normalizer   The normalizer
  555.      * @param bool     $forcePrepend If set to true, prepend instead of appending
  556.      *
  557.      * @return $this
  558.      *
  559.      * @throws UndefinedOptionsException If the option is undefined
  560.      * @throws AccessException           If called from a lazy option or normalizer
  561.      */
  562.     public function addNormalizer(string $option, \Closure $normalizer, bool $forcePrepend = false): self
  563.     {
  564.         if ($this->locked) {
  565.             throw new AccessException('Normalizers cannot be set from a lazy option or normalizer.');
  566.         }
  568.         if (!isset($this->defined[$option])) {
  569.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  570.         }
  572.         if ($forcePrepend) {
  573.             $this->normalizers[$option] = $this->normalizers[$option] ?? [];
  574.             array_unshift($this->normalizers[$option], $normalizer);
  575.         } else {
  576.             $this->normalizers[$option][] = $normalizer;
  577.         }
  579.         // Make sure the option is processed
  580.         unset($this->resolved[$option]);
  582.         return $this;
  583.     }
  585.     /**
  586.      * Sets allowed values for an option.
  587.      *
  588.      * Instead of passing values, you may also pass a closures with the
  589.      * following signature:
  590.      *
  591.      *     function ($value) {
  592.      *         // return true or false
  593.      *     }
  594.      *
  595.      * The closure receives the value as argument and should return true to
  596.      * accept the value and false to reject the value.
  597.      *
  598.      * @param string $option        The option name
  599.      * @param mixed  $allowedValues One or more acceptable values/closures
  600.      *
  601.      * @return $this
  602.      *
  603.      * @throws UndefinedOptionsException If the option is undefined
  604.      * @throws AccessException           If called from a lazy option or normalizer
  605.      */
  606.     public function setAllowedValues(string $option, $allowedValues)
  607.     {
  608.         if ($this->locked) {
  609.             throw new AccessException('Allowed values cannot be set from a lazy option or normalizer.');
  610.         }
  612.         if (!isset($this->defined[$option])) {
  613.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  614.         }
  616.         $this->allowedValues[$option] = \is_array($allowedValues) ? $allowedValues : [$allowedValues];
  618.         // Make sure the option is processed
  619.         unset($this->resolved[$option]);
  621.         return $this;
  622.     }
  624.     /**
  625.      * Adds allowed values for an option.
  626.      *
  627.      * The values are merged with the allowed values defined previously.
  628.      *
  629.      * Instead of passing values, you may also pass a closures with the
  630.      * following signature:
  631.      *
  632.      *     function ($value) {
  633.      *         // return true or false
  634.      *     }
  635.      *
  636.      * The closure receives the value as argument and should return true to
  637.      * accept the value and false to reject the value.
  638.      *
  639.      * @param string $option        The option name
  640.      * @param mixed  $allowedValues One or more acceptable values/closures
  641.      *
  642.      * @return $this
  643.      *
  644.      * @throws UndefinedOptionsException If the option is undefined
  645.      * @throws AccessException           If called from a lazy option or normalizer
  646.      */
  647.     public function addAllowedValues(string $option, $allowedValues)
  648.     {
  649.         if ($this->locked) {
  650.             throw new AccessException('Allowed values cannot be added from a lazy option or normalizer.');
  651.         }
  653.         if (!isset($this->defined[$option])) {
  654.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  655.         }
  657.         if (!\is_array($allowedValues)) {
  658.             $allowedValues = [$allowedValues];
  659.         }
  661.         if (!isset($this->allowedValues[$option])) {
  662.             $this->allowedValues[$option] = $allowedValues;
  663.         } else {
  664.             $this->allowedValues[$option] = array_merge($this->allowedValues[$option], $allowedValues);
  665.         }
  667.         // Make sure the option is processed
  668.         unset($this->resolved[$option]);
  670.         return $this;
  671.     }
  673.     /**
  674.      * Sets allowed types for an option.
  675.      *
  676.      * Any type for which a corresponding is_<type>() function exists is
  677.      * acceptable. Additionally, fully-qualified class or interface names may
  678.      * be passed.
  679.      *
  680.      * @param string          $option       The option name
  681.      * @param string|string[] $allowedTypes One or more accepted types
  682.      *
  683.      * @return $this
  684.      *
  685.      * @throws UndefinedOptionsException If the option is undefined
  686.      * @throws AccessException           If called from a lazy option or normalizer
  687.      */
  688.     public function setAllowedTypes(string $option, $allowedTypes)
  689.     {
  690.         if ($this->locked) {
  691.             throw new AccessException('Allowed types cannot be set from a lazy option or normalizer.');
  692.         }
  694.         if (!isset($this->defined[$option])) {
  695.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  696.         }
  698.         $this->allowedTypes[$option] = (array) $allowedTypes;
  700.         // Make sure the option is processed
  701.         unset($this->resolved[$option]);
  703.         return $this;
  704.     }
  706.     /**
  707.      * Adds allowed types for an option.
  708.      *
  709.      * The types are merged with the allowed types defined previously.
  710.      *
  711.      * Any type for which a corresponding is_<type>() function exists is
  712.      * acceptable. Additionally, fully-qualified class or interface names may
  713.      * be passed.
  714.      *
  715.      * @param string          $option       The option name
  716.      * @param string|string[] $allowedTypes One or more accepted types
  717.      *
  718.      * @return $this
  719.      *
  720.      * @throws UndefinedOptionsException If the option is undefined
  721.      * @throws AccessException           If called from a lazy option or normalizer
  722.      */
  723.     public function addAllowedTypes(string $option, $allowedTypes)
  724.     {
  725.         if ($this->locked) {
  726.             throw new AccessException('Allowed types cannot be added from a lazy option or normalizer.');
  727.         }
  729.         if (!isset($this->defined[$option])) {
  730.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  731.         }
  733.         if (!isset($this->allowedTypes[$option])) {
  734.             $this->allowedTypes[$option] = (array) $allowedTypes;
  735.         } else {
  736.             $this->allowedTypes[$option] = array_merge($this->allowedTypes[$option], (array) $allowedTypes);
  737.         }
  739.         // Make sure the option is processed
  740.         unset($this->resolved[$option]);
  742.         return $this;
  743.     }
  745.     /**
  746.      * Defines an option configurator with the given name.
  747.      */
  748.     public function define(string $option): OptionConfigurator
  749.     {
  750.         if (isset($this->defined[$option])) {
  751.             throw new OptionDefinitionException(sprintf('The option "%s" is already defined.', $option));
  752.         }
  754.         return new OptionConfigurator($option, $this);
  755.     }
  757.     /**
  758.      * Sets an info message for an option.
  759.      *
  760.      * @return $this
  761.      *
  762.      * @throws UndefinedOptionsException If the option is undefined
  763.      * @throws AccessException           If called from a lazy option or normalizer
  764.      */
  765.     public function setInfo(string $option, string $info): self
  766.     {
  767.         if ($this->locked) {
  768.             throw new AccessException('The Info message cannot be set from a lazy option or normalizer.');
  769.         }
  771.         if (!isset($this->defined[$option])) {
  772.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  773.         }
  775.         $this->info[$option] = $info;
  777.         return $this;
  778.     }
  780.     /**
  781.      * Gets the info message for an option.
  782.      */
  783.     public function getInfo(string $option): ?string
  784.     {
  785.         if (!isset($this->defined[$option])) {
  786.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  787.         }
  789.         return $this->info[$option] ?? null;
  790.     }
  792.     /**
  793.      * Removes the option with the given name.
  794.      *
  795.      * Undefined options are ignored.
  796.      *
  797.      * @param string|string[] $optionNames One or more option names
  798.      *
  799.      * @return $this
  800.      *
  801.      * @throws AccessException If called from a lazy option or normalizer
  802.      */
  803.     public function remove($optionNames)
  804.     {
  805.         if ($this->locked) {
  806.             throw new AccessException('Options cannot be removed from a lazy option or normalizer.');
  807.         }
  809.         foreach ((array) $optionNames as $option) {
  810.             unset($this->defined[$option], $this->defaults[$option], $this->required[$option], $this->resolved[$option]);
  811.             unset($this->lazy[$option], $this->normalizers[$option], $this->allowedTypes[$option], $this->allowedValues[$option], $this->info[$option]);
  812.         }
  814.         return $this;
  815.     }
  817.     /**
  818.      * Removes all options.
  819.      *
  820.      * @return $this
  821.      *
  822.      * @throws AccessException If called from a lazy option or normalizer
  823.      */
  824.     public function clear()
  825.     {
  826.         if ($this->locked) {
  827.             throw new AccessException('Options cannot be cleared from a lazy option or normalizer.');
  828.         }
  830.         $this->defined = [];
  831.         $this->defaults = [];
  832.         $this->nested = [];
  833.         $this->required = [];
  834.         $this->resolved = [];
  835.         $this->lazy = [];
  836.         $this->normalizers = [];
  837.         $this->allowedTypes = [];
  838.         $this->allowedValues = [];
  839.         $this->deprecated = [];
  840.         $this->info = [];
  842.         return $this;
  843.     }
  845.     /**
  846.      * Merges options with the default values stored in the container and
  847.      * validates them.
  848.      *
  849.      * Exceptions are thrown if:
  850.      *
  851.      *  - Undefined options are passed;
  852.      *  - Required options are missing;
  853.      *  - Options have invalid types;
  854.      *  - Options have invalid values.
  855.      *
  856.      * @param array $options A map of option names to values
  857.      *
  858.      * @return array The merged and validated options
  859.      *
  860.      * @throws UndefinedOptionsException If an option name is undefined
  861.      * @throws InvalidOptionsException   If an option doesn't fulfill the
  862.      *                                   specified validation rules
  863.      * @throws MissingOptionsException   If a required option is missing
  864.      * @throws OptionDefinitionException If there is a cyclic dependency between
  865.      *                                   lazy options and/or normalizers
  866.      * @throws NoSuchOptionException     If a lazy option reads an unavailable option
  867.      * @throws AccessException           If called from a lazy option or normalizer
  868.      */
  869.     public function resolve(array $options = [])
  870.     {
  871.         if ($this->locked) {
  872.             throw new AccessException('Options cannot be resolved from a lazy option or normalizer.');
  873.         }
  875.         // Allow this method to be called multiple times
  876.         $clone = clone $this;
  878.         // Make sure that no unknown options are passed
  879.         $diff = array_diff_key($options, $clone->defined);
  881.         if (\count($diff) > 0) {
  882.             ksort($clone->defined);
  883.             ksort($diff);
  885.             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))));
  886.         }
  888.         // Override options set by the user
  889.         foreach ($options as $option => $value) {
  890.             $clone->given[$option] = true;
  891.             $clone->defaults[$option] = $value;
  892.             unset($clone->resolved[$option], $clone->lazy[$option]);
  893.         }
  895.         // Check whether any required option is missing
  896.         $diff = array_diff_key($clone->required, $clone->defaults);
  898.         if (\count($diff) > 0) {
  899.             ksort($diff);
  901.             throw new MissingOptionsException(sprintf(\count($diff) > 1 ? 'The required options "%s" are missing.' : 'The required option "%s" is missing.', $this->formatOptions(array_keys($diff))));
  902.         }
  904.         // Lock the container
  905.         $clone->locked = true;
  907.         // Now process the individual options. Use offsetGet(), which resolves
  908.         // the option itself and any options that the option depends on
  909.         foreach ($clone->defaults as $option => $_) {
  910.             $clone->offsetGet($option);
  911.         }
  913.         return $clone->resolved;
  914.     }
  916.     /**
  917.      * Returns the resolved value of an option.
  918.      *
  919.      * @param string $option             The option name
  920.      * @param bool   $triggerDeprecation Whether to trigger the deprecation or not (true by default)
  921.      *
  922.      * @return mixed The option value
  923.      *
  924.      * @throws AccessException           If accessing this method outside of
  925.      *                                   {@link resolve()}
  926.      * @throws NoSuchOptionException     If the option is not set
  927.      * @throws InvalidOptionsException   If the option doesn't fulfill the
  928.      *                                   specified validation rules
  929.      * @throws OptionDefinitionException If there is a cyclic dependency between
  930.      *                                   lazy options and/or normalizers
  931.      */
  932.     public function offsetGet($option, bool $triggerDeprecation = true)
  933.     {
  934.         if (!$this->locked) {
  935.             throw new AccessException('Array access is only supported within closures of lazy options and normalizers.');
  936.         }
  938.         // Shortcut for resolved options
  939.         if (isset($this->resolved[$option]) || \array_key_exists($option, $this->resolved)) {
  940.             if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || $this->calling) && \is_string($this->deprecated[$option]['message'])) {
  941.                 trigger_deprecation($this->deprecated[$option]['package'], $this->deprecated[$option]['version'], strtr($this->deprecated[$option]['message'], ['%name%' => $option]));
  942.             }
  944.             return $this->resolved[$option];
  945.         }
  947.         // Check whether the option is set at all
  948.         if (!isset($this->defaults[$option]) && !\array_key_exists($option, $this->defaults)) {
  949.             if (!isset($this->defined[$option])) {
  950.                 throw new NoSuchOptionException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  951.             }
  953.             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])));
  954.         }
  956.         $value = $this->defaults[$option];
  958.         // Resolve the option if it is a nested definition
  959.         if (isset($this->nested[$option])) {
  960.             // If the closure is already being called, we have a cyclic dependency
  961.             if (isset($this->calling[$option])) {
  962.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  963.             }
  965.             if (!\is_array($value)) {
  966.                 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), get_debug_type($value)));
  967.             }
  969.             // The following section must be protected from cyclic calls.
  970.             $this->calling[$option] = true;
  971.             try {
  972.                 $resolver = new self();
  973.                 $resolver->parentsOptions = $this->parentsOptions;
  974.                 $resolver->parentsOptions[] = $option;
  975.                 foreach ($this->nested[$option] as $closure) {
  976.                     $closure($resolver, $this);
  977.                 }
  978.                 $value = $resolver->resolve($value);
  979.             } finally {
  980.                 unset($this->calling[$option]);
  981.             }
  982.         }
  984.         // Resolve the option if the default value is lazily evaluated
  985.         if (isset($this->lazy[$option])) {
  986.             // If the closure is already being called, we have a cyclic
  987.             // dependency
  988.             if (isset($this->calling[$option])) {
  989.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  990.             }
  992.             // The following section must be protected from cyclic
  993.             // calls. Set $calling for the current $option to detect a cyclic
  994.             // dependency
  995.             // BEGIN
  996.             $this->calling[$option] = true;
  997.             try {
  998.                 foreach ($this->lazy[$option] as $closure) {
  999.                     $value = $closure($this, $value);
  1000.                 }
  1001.             } finally {
  1002.                 unset($this->calling[$option]);
  1003.             }
  1004.             // END
  1005.         }
  1007.         // Validate the type of the resolved option
  1008.         if (isset($this->allowedTypes[$option])) {
  1009.             $valid = true;
  1010.             $invalidTypes = [];
  1012.             foreach ($this->allowedTypes[$option] as $type) {
  1013.                 if ($valid = $this->verifyTypes($type, $value, $invalidTypes)) {
  1014.                     break;
  1015.                 }
  1016.             }
  1018.             if (!$valid) {
  1019.                 $fmtActualValue = $this->formatValue($value);
  1020.                 $fmtAllowedTypes = implode('" or "', $this->allowedTypes[$option]);
  1021.                 $fmtProvidedTypes = implode('|', array_keys($invalidTypes));
  1022.                 $allowedContainsArrayType = \count(array_filter($this->allowedTypes[$option], static function ($item) {
  1023.                     return '[]' === substr($item, -2);
  1024.                 })) > 0;
  1026.                 if (\is_array($value) && $allowedContainsArrayType) {
  1027.                     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));
  1028.                 }
  1030.                 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));
  1031.             }
  1032.         }
  1034.         // Validate the value of the resolved option
  1035.         if (isset($this->allowedValues[$option])) {
  1036.             $success = false;
  1037.             $printableAllowedValues = [];
  1039.             foreach ($this->allowedValues[$option] as $allowedValue) {
  1040.                 if ($allowedValue instanceof \Closure) {
  1041.                     if ($allowedValue($value)) {
  1042.                         $success = true;
  1043.                         break;
  1044.                     }
  1046.                     // Don't include closures in the exception message
  1047.                     continue;
  1048.                 }
  1050.                 if ($value === $allowedValue) {
  1051.                     $success = true;
  1052.                     break;
  1053.                 }
  1055.                 $printableAllowedValues[] = $allowedValue;
  1056.             }
  1058.             if (!$success) {
  1059.                 $message = sprintf(
  1060.                     'The option "%s" with value %s is invalid.',
  1061.                     $option,
  1062.                     $this->formatValue($value)
  1063.                 );
  1065.                 if (\count($printableAllowedValues) > 0) {
  1066.                     $message .= sprintf(
  1067.                         ' Accepted values are: %s.',
  1068.                         $this->formatValues($printableAllowedValues)
  1069.                     );
  1070.                 }
  1072.                 if (isset($this->info[$option])) {
  1073.                     $message .= sprintf(' Info: %s.', $this->info[$option]);
  1074.                 }
  1076.                 throw new InvalidOptionsException($message);
  1077.             }
  1078.         }
  1080.         // Check whether the option is deprecated
  1081.         // and it is provided by the user or is being called from a lazy evaluation
  1082.         if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || ($this->calling && \is_string($this->deprecated[$option]['message'])))) {
  1083.             $deprecation = $this->deprecated[$option];
  1084.             $message = $this->deprecated[$option]['message'];
  1086.             if ($message instanceof \Closure) {
  1087.                 // If the closure is already being called, we have a cyclic dependency
  1088.                 if (isset($this->calling[$option])) {
  1089.                     throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  1090.                 }
  1092.                 $this->calling[$option] = true;
  1093.                 try {
  1094.                     if (!\is_string($message = $message($this, $value))) {
  1095.                         throw new InvalidOptionsException(sprintf('Invalid type for deprecation message, expected string but got "%s", return an empty string to ignore.', get_debug_type($message)));
  1096.                     }
  1097.                 } finally {
  1098.                     unset($this->calling[$option]);
  1099.                 }
  1100.             }
  1102.             if ('' !== $message) {
  1103.                 trigger_deprecation($deprecation['package'], $deprecation['version'], strtr($message, ['%name%' => $option]));
  1104.             }
  1105.         }
  1107.         // Normalize the validated option
  1108.         if (isset($this->normalizers[$option])) {
  1109.             // If the closure is already being called, we have a cyclic
  1110.             // dependency
  1111.             if (isset($this->calling[$option])) {
  1112.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  1113.             }
  1115.             // The following section must be protected from cyclic
  1116.             // calls. Set $calling for the current $option to detect a cyclic
  1117.             // dependency
  1118.             // BEGIN
  1119.             $this->calling[$option] = true;
  1120.             try {
  1121.                 foreach ($this->normalizers[$option] as $normalizer) {
  1122.                     $value = $normalizer($this, $value);
  1123.                 }
  1124.             } finally {
  1125.                 unset($this->calling[$option]);
  1126.             }
  1127.             // END
  1128.         }
  1130.         // Mark as resolved
  1131.         $this->resolved[$option] = $value;
  1133.         return $value;
  1134.     }
  1136.     private function verifyTypes(string $type, $value, array &$invalidTypes, int $level = 0): bool
  1137.     {
  1138.         if (\is_array($value) && '[]' === substr($type, -2)) {
  1139.             $type = substr($type, 0, -2);
  1140.             $valid = true;
  1142.             foreach ($value as $val) {
  1143.                 if (!$this->verifyTypes($type, $val, $invalidTypes, $level + 1)) {
  1144.                     $valid = false;
  1145.                 }
  1146.             }
  1148.             return $valid;
  1149.         }
  1151.         if (('null' === $type && null === $value) || (isset(self::VALIDATION_FUNCTIONS[$type]) ? self::VALIDATION_FUNCTIONS[$type]($value) : $value instanceof $type)) {
  1152.             return true;
  1153.         }
  1155.         if (!$invalidTypes || $level > 0) {
  1156.             $invalidTypes[get_debug_type($value)] = true;
  1157.         }
  1159.         return false;
  1160.     }
  1162.     /**
  1163.      * Returns whether a resolved option with the given name exists.
  1164.      *
  1165.      * @param string $option The option name
  1166.      *
  1167.      * @return bool Whether the option is set
  1168.      *
  1169.      * @throws AccessException If accessing this method outside of {@link resolve()}
  1170.      *
  1171.      * @see \ArrayAccess::offsetExists()
  1172.      */
  1173.     public function offsetExists($option)
  1174.     {
  1175.         if (!$this->locked) {
  1176.             throw new AccessException('Array access is only supported within closures of lazy options and normalizers.');
  1177.         }
  1179.         return \array_key_exists($option, $this->defaults);
  1180.     }
  1182.     /**
  1183.      * Not supported.
  1184.      *
  1185.      * @throws AccessException
  1186.      */
  1187.     public function offsetSet($option, $value)
  1188.     {
  1189.         throw new AccessException('Setting options via array access is not supported. Use setDefault() instead.');
  1190.     }
  1192.     /**
  1193.      * Not supported.
  1194.      *
  1195.      * @throws AccessException
  1196.      */
  1197.     public function offsetUnset($option)
  1198.     {
  1199.         throw new AccessException('Removing options via array access is not supported. Use remove() instead.');
  1200.     }
  1202.     /**
  1203.      * Returns the number of set options.
  1204.      *
  1205.      * This may be only a subset of the defined options.
  1206.      *
  1207.      * @return int Number of options
  1208.      *
  1209.      * @throws AccessException If accessing this method outside of {@link resolve()}
  1210.      *
  1211.      * @see \Countable::count()
  1212.      */
  1213.     public function count()
  1214.     {
  1215.         if (!$this->locked) {
  1216.             throw new AccessException('Counting is only supported within closures of lazy options and normalizers.');
  1217.         }
  1219.         return \count($this->defaults);
  1220.     }
  1222.     /**
  1223.      * Returns a string representation of the value.
  1224.      *
  1225.      * This method returns the equivalent PHP tokens for most scalar types
  1226.      * (i.e. "false" for false, "1" for 1 etc.). Strings are always wrapped
  1227.      * in double quotes (").
  1228.      *
  1229.      * @param mixed $value The value to format as string
  1230.      */
  1231.     private function formatValue($value): string
  1232.     {
  1233.         if (\is_object($value)) {
  1234.             return \get_class($value);
  1235.         }
  1237.         if (\is_array($value)) {
  1238.             return 'array';
  1239.         }
  1241.         if (\is_string($value)) {
  1242.             return '"'.$value.'"';
  1243.         }
  1245.         if (\is_resource($value)) {
  1246.             return 'resource';
  1247.         }
  1249.         if (null === $value) {
  1250.             return 'null';
  1251.         }
  1253.         if (false === $value) {
  1254.             return 'false';
  1255.         }
  1257.         if (true === $value) {
  1258.             return 'true';
  1259.         }
  1261.         return (string) $value;
  1262.     }
  1264.     /**
  1265.      * Returns a string representation of a list of values.
  1266.      *
  1267.      * Each of the values is converted to a string using
  1268.      * {@link formatValue()}. The values are then concatenated with commas.
  1269.      *
  1270.      * @see formatValue()
  1271.      */
  1272.     private function formatValues(array $values): string
  1273.     {
  1274.         foreach ($values as $key => $value) {
  1275.             $values[$key] = $this->formatValue($value);
  1276.         }
  1278.         return implode(', ', $values);
  1279.     }
  1281.     private function formatOptions(array $options): string
  1282.     {
  1283.         if ($this->parentsOptions) {
  1284.             $prefix = array_shift($this->parentsOptions);
  1285.             if ($this->parentsOptions) {
  1286.                 $prefix .= sprintf('[%s]', implode('][', $this->parentsOptions));
  1287.             }
  1289.             $options = array_map(static function (string $option) use ($prefix): string {
  1290.                 return sprintf('%s[%s]', $prefix, $option);
  1291.             }, $options);
  1292.         }
  1294.         return implode('", "', $options);
  1295.     }
  1297.     private function getParameterClassName(\ReflectionParameter $parameter): ?string
  1298.     {
  1299.         if (!($type = $parameter->getType()) instanceof \ReflectionNamedType || $type->isBuiltin()) {
  1300.             return null;
  1301.         }
  1303.         return $type->getName();
  1304.     }
  1305. }