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

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.      * Whether the whole options definition is marked as array prototype.
  135.      */
  136.     private $prototype;
  138.     /**
  139.      * The prototype array's index that is being read.
  140.      */
  141.     private $prototypeIndex;
  143.     /**
  144.      * Whether to ignore undefined options.
  145.      */
  146.     private bool $ignoreUndefined = false;
  148.     /**
  149.      * Sets the default value of a given option.
  150.      *
  151.      * If the default value should be set based on other options, you can pass
  152.      * a closure with the following signature:
  153.      *
  154.      *     function (Options $options) {
  155.      *         // ...
  156.      *     }
  157.      *
  158.      * The closure will be evaluated when {@link resolve()} is called. The
  159.      * closure has access to the resolved values of other options through the
  160.      * passed {@link Options} instance:
  161.      *
  162.      *     function (Options $options) {
  163.      *         if (isset($options['port'])) {
  164.      *             // ...
  165.      *         }
  166.      *     }
  167.      *
  168.      * If you want to access the previously set default value, add a second
  169.      * argument to the closure's signature:
  170.      *
  171.      *     $options->setDefault('name', 'Default Name');
  172.      *
  173.      *     $options->setDefault('name', function (Options $options, $previousValue) {
  174.      *         // 'Default Name' === $previousValue
  175.      *     });
  176.      *
  177.      * This is mostly useful if the configuration of the {@link Options} object
  178.      * is spread across different locations of your code, such as base and
  179.      * sub-classes.
  180.      *
  181.      * If you want to define nested options, you can pass a closure with the
  182.      * following signature:
  183.      *
  184.      *     $options->setDefault('database', function (OptionsResolver $resolver) {
  185.      *         $resolver->setDefined(['dbname', 'host', 'port', 'user', 'pass']);
  186.      *     }
  187.      *
  188.      * To get access to the parent options, add a second argument to the closure's
  189.      * signature:
  190.      *
  191.      *     function (OptionsResolver $resolver, Options $parent) {
  192.      *         // 'default' === $parent['connection']
  193.      *     }
  194.      *
  195.      * @return $this
  196.      *
  197.      * @throws AccessException If called from a lazy option or normalizer
  198.      */
  199.     public function setDefault(string $option, mixed $value): static
  200.     {
  201.         // Setting is not possible once resolving starts, because then lazy
  202.         // options could manipulate the state of the object, leading to
  203.         // inconsistent results.
  204.         if ($this->locked) {
  205.             throw new AccessException('Default values cannot be set from a lazy option or normalizer.');
  206.         }
  208.         // If an option is a closure that should be evaluated lazily, store it
  209.         // in the "lazy" property.
  210.         if ($value instanceof \Closure) {
  211.             $reflClosure = new \ReflectionFunction($value);
  212.             $params = $reflClosure->getParameters();
  214.             if (isset($params[0]) && Options::class === $this->getParameterClassName($params[0])) {
  215.                 // Initialize the option if no previous value exists
  216.                 if (!isset($this->defaults[$option])) {
  217.                     $this->defaults[$option] = null;
  218.                 }
  220.                 // Ignore previous lazy options if the closure has no second parameter
  221.                 if (!isset($this->lazy[$option]) || !isset($params[1])) {
  222.                     $this->lazy[$option] = [];
  223.                 }
  225.                 // Store closure for later evaluation
  226.                 $this->lazy[$option][] = $value;
  227.                 $this->defined[$option] = true;
  229.                 // Make sure the option is processed and is not nested anymore
  230.                 unset($this->resolved[$option], $this->nested[$option]);
  232.                 return $this;
  233.             }
  235.             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()))) {
  236.                 // Store closure for later evaluation
  237.                 $this->nested[$option][] = $value;
  238.                 $this->defaults[$option] = [];
  239.                 $this->defined[$option] = true;
  241.                 // Make sure the option is processed and is not lazy anymore
  242.                 unset($this->resolved[$option], $this->lazy[$option]);
  244.                 return $this;
  245.             }
  246.         }
  248.         // This option is not lazy nor nested anymore
  249.         unset($this->lazy[$option], $this->nested[$option]);
  251.         // Yet undefined options can be marked as resolved, because we only need
  252.         // to resolve options with lazy closures, normalizers or validation
  253.         // rules, none of which can exist for undefined options
  254.         // If the option was resolved before, update the resolved value
  255.         if (!isset($this->defined[$option]) || \array_key_exists($option, $this->resolved)) {
  256.             $this->resolved[$option] = $value;
  257.         }
  259.         $this->defaults[$option] = $value;
  260.         $this->defined[$option] = true;
  262.         return $this;
  263.     }
  265.     /**
  266.      * @return $this
  267.      *
  268.      * @throws AccessException If called from a lazy option or normalizer
  269.      */
  270.     public function setDefaults(array $defaults): static
  271.     {
  272.         foreach ($defaults as $option => $value) {
  273.             $this->setDefault($option, $value);
  274.         }
  276.         return $this;
  277.     }
  279.     /**
  280.      * Returns whether a default value is set for an option.
  281.      *
  282.      * Returns true if {@link setDefault()} was called for this option.
  283.      * An option is also considered set if it was set to null.
  284.      */
  285.     public function hasDefault(string $option): bool
  286.     {
  287.         return \array_key_exists($option, $this->defaults);
  288.     }
  290.     /**
  291.      * Marks one or more options as required.
  292.      *
  293.      * @param string|string[] $optionNames One or more option names
  294.      *
  295.      * @return $this
  296.      *
  297.      * @throws AccessException If called from a lazy option or normalizer
  298.      */
  299.     public function setRequired(string|array $optionNames): static
  300.     {
  301.         if ($this->locked) {
  302.             throw new AccessException('Options cannot be made required from a lazy option or normalizer.');
  303.         }
  305.         foreach ((array) $optionNames as $option) {
  306.             $this->defined[$option] = true;
  307.             $this->required[$option] = true;
  308.         }
  310.         return $this;
  311.     }
  313.     /**
  314.      * Returns whether an option is required.
  315.      *
  316.      * An option is required if it was passed to {@link setRequired()}.
  317.      */
  318.     public function isRequired(string $option): bool
  319.     {
  320.         return isset($this->required[$option]);
  321.     }
  323.     /**
  324.      * Returns the names of all required options.
  325.      *
  326.      * @return string[]
  327.      *
  328.      * @see isRequired()
  329.      */
  330.     public function getRequiredOptions(): array
  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.     public function isMissing(string $option): bool
  343.     {
  344.         return isset($this->required[$option]) && !\array_key_exists($option, $this->defaults);
  345.     }
  347.     /**
  348.      * Returns the names of all options missing a default value.
  349.      *
  350.      * @return string[]
  351.      */
  352.     public function getMissingOptions(): array
  353.     {
  354.         return array_keys(array_diff_key($this->required, $this->defaults));
  355.     }
  357.     /**
  358.      * Defines a valid option name.
  359.      *
  360.      * Defines an option name without setting a default value. The option will
  361.      * be accepted when passed to {@link resolve()}. When not passed, the
  362.      * option will not be included in the resolved options.
  363.      *
  364.      * @param string|string[] $optionNames One or more option names
  365.      *
  366.      * @return $this
  367.      *
  368.      * @throws AccessException If called from a lazy option or normalizer
  369.      */
  370.     public function setDefined(string|array $optionNames): static
  371.     {
  372.         if ($this->locked) {
  373.             throw new AccessException('Options cannot be defined from a lazy option or normalizer.');
  374.         }
  376.         foreach ((array) $optionNames as $option) {
  377.             $this->defined[$option] = true;
  378.         }
  380.         return $this;
  381.     }
  383.     /**
  384.      * Returns whether an option is defined.
  385.      *
  386.      * Returns true for any option passed to {@link setDefault()},
  387.      * {@link setRequired()} or {@link setDefined()}.
  388.      */
  389.     public function isDefined(string $option): bool
  390.     {
  391.         return isset($this->defined[$option]);
  392.     }
  394.     /**
  395.      * Returns the names of all defined options.
  396.      *
  397.      * @return string[]
  398.      *
  399.      * @see isDefined()
  400.      */
  401.     public function getDefinedOptions(): array
  402.     {
  403.         return array_keys($this->defined);
  404.     }
  406.     public function isNested(string $option): bool
  407.     {
  408.         return isset($this->nested[$option]);
  409.     }
  411.     /**
  412.      * Deprecates an option, allowed types or values.
  413.      *
  414.      * Instead of passing the message, you may also pass a closure with the
  415.      * following signature:
  416.      *
  417.      *     function (Options $options, $value): string {
  418.      *         // ...
  419.      *     }
  420.      *
  421.      * The closure receives the value as argument and should return a string.
  422.      * Return an empty string to ignore the option deprecation.
  423.      *
  424.      * The closure is invoked when {@link resolve()} is called. The parameter
  425.      * passed to the closure is the value of the option after validating it
  426.      * and before normalizing it.
  427.      *
  428.      * @param string          $package The name of the composer package that is triggering the deprecation
  429.      * @param string          $version The version of the package that introduced the deprecation
  430.      * @param string|\Closure $message The deprecation message to use
  431.      *
  432.      * @return $this
  433.      */
  434.     public function setDeprecated(string $option, string $package, string $version, string|\Closure $message = 'The option "%name%" is deprecated.'): static
  435.     {
  436.         if ($this->locked) {
  437.             throw new AccessException('Options cannot be deprecated from a lazy option or normalizer.');
  438.         }
  440.         if (!isset($this->defined[$option])) {
  441.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist, defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  442.         }
  444.         if (!\is_string($message) && !$message instanceof \Closure) {
  445.             throw new InvalidArgumentException(sprintf('Invalid type for deprecation message argument, expected string or \Closure, but got "%s".', get_debug_type($message)));
  446.         }
  448.         // ignore if empty string
  449.         if ('' === $message) {
  450.             return $this;
  451.         }
  453.         $this->deprecated[$option] = [
  454.             'package' => $package,
  455.             'version' => $version,
  456.             'message' => $message,
  457.         ];
  459.         // Make sure the option is processed
  460.         unset($this->resolved[$option]);
  462.         return $this;
  463.     }
  465.     public function isDeprecated(string $option): bool
  466.     {
  467.         return isset($this->deprecated[$option]);
  468.     }
  470.     /**
  471.      * Sets the normalizer for an option.
  472.      *
  473.      * The normalizer should be a closure with the following signature:
  474.      *
  475.      *     function (Options $options, $value) {
  476.      *         // ...
  477.      *     }
  478.      *
  479.      * The closure is invoked when {@link resolve()} is called. The closure
  480.      * has access to the resolved values of other options through the passed
  481.      * {@link Options} instance.
  482.      *
  483.      * The second parameter passed to the closure is the value of
  484.      * the option.
  485.      *
  486.      * The resolved option value is set to the return value of the closure.
  487.      *
  488.      * @return $this
  489.      *
  490.      * @throws UndefinedOptionsException If the option is undefined
  491.      * @throws AccessException           If called from a lazy option or normalizer
  492.      */
  493.     public function setNormalizer(string $option, \Closure $normalizer)
  494.     {
  495.         if ($this->locked) {
  496.             throw new AccessException('Normalizers cannot be set from a lazy option or normalizer.');
  497.         }
  499.         if (!isset($this->defined[$option])) {
  500.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  501.         }
  503.         $this->normalizers[$option] = [$normalizer];
  505.         // Make sure the option is processed
  506.         unset($this->resolved[$option]);
  508.         return $this;
  509.     }
  511.     /**
  512.      * Adds a normalizer for an option.
  513.      *
  514.      * The normalizer should be a closure with the following signature:
  515.      *
  516.      *     function (Options $options, $value): mixed {
  517.      *         // ...
  518.      *     }
  519.      *
  520.      * The closure is invoked when {@link resolve()} is called. The closure
  521.      * has access to the resolved values of other options through the passed
  522.      * {@link Options} instance.
  523.      *
  524.      * The second parameter passed to the closure is the value of
  525.      * the option.
  526.      *
  527.      * The resolved option value is set to the return value of the closure.
  528.      *
  529.      * @return $this
  530.      *
  531.      * @throws UndefinedOptionsException If the option is undefined
  532.      * @throws AccessException           If called from a lazy option or normalizer
  533.      */
  534.     public function addNormalizer(string $option, \Closure $normalizer, bool $forcePrepend = false): static
  535.     {
  536.         if ($this->locked) {
  537.             throw new AccessException('Normalizers cannot be set from a lazy option or normalizer.');
  538.         }
  540.         if (!isset($this->defined[$option])) {
  541.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  542.         }
  544.         if ($forcePrepend) {
  545.             $this->normalizers[$option] ??= [];
  546.             array_unshift($this->normalizers[$option], $normalizer);
  547.         } else {
  548.             $this->normalizers[$option][] = $normalizer;
  549.         }
  551.         // Make sure the option is processed
  552.         unset($this->resolved[$option]);
  554.         return $this;
  555.     }
  557.     /**
  558.      * Sets allowed values for an option.
  559.      *
  560.      * Instead of passing values, you may also pass a closures with the
  561.      * following signature:
  562.      *
  563.      *     function ($value) {
  564.      *         // return true or false
  565.      *     }
  566.      *
  567.      * The closure receives the value as argument and should return true to
  568.      * accept the value and false to reject the value.
  569.      *
  570.      * @param mixed $allowedValues One or more acceptable values/closures
  571.      *
  572.      * @return $this
  573.      *
  574.      * @throws UndefinedOptionsException If the option is undefined
  575.      * @throws AccessException           If called from a lazy option or normalizer
  576.      */
  577.     public function setAllowedValues(string $option, mixed $allowedValues)
  578.     {
  579.         if ($this->locked) {
  580.             throw new AccessException('Allowed values cannot be set from a lazy option or normalizer.');
  581.         }
  583.         if (!isset($this->defined[$option])) {
  584.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  585.         }
  587.         $this->allowedValues[$option] = \is_array($allowedValues) ? $allowedValues : [$allowedValues];
  589.         // Make sure the option is processed
  590.         unset($this->resolved[$option]);
  592.         return $this;
  593.     }
  595.     /**
  596.      * Adds allowed values for an option.
  597.      *
  598.      * The values are merged with the allowed values defined previously.
  599.      *
  600.      * Instead of passing values, you may also pass a closures with the
  601.      * following signature:
  602.      *
  603.      *     function ($value) {
  604.      *         // return true or false
  605.      *     }
  606.      *
  607.      * The closure receives the value as argument and should return true to
  608.      * accept the value and false to reject the value.
  609.      *
  610.      * @param mixed $allowedValues One or more acceptable values/closures
  611.      *
  612.      * @return $this
  613.      *
  614.      * @throws UndefinedOptionsException If the option is undefined
  615.      * @throws AccessException           If called from a lazy option or normalizer
  616.      */
  617.     public function addAllowedValues(string $option, mixed $allowedValues)
  618.     {
  619.         if ($this->locked) {
  620.             throw new AccessException('Allowed values cannot be added from a lazy option or normalizer.');
  621.         }
  623.         if (!isset($this->defined[$option])) {
  624.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  625.         }
  627.         if (!\is_array($allowedValues)) {
  628.             $allowedValues = [$allowedValues];
  629.         }
  631.         if (!isset($this->allowedValues[$option])) {
  632.             $this->allowedValues[$option] = $allowedValues;
  633.         } else {
  634.             $this->allowedValues[$option] = array_merge($this->allowedValues[$option], $allowedValues);
  635.         }
  637.         // Make sure the option is processed
  638.         unset($this->resolved[$option]);
  640.         return $this;
  641.     }
  643.     /**
  644.      * Sets allowed types for an option.
  645.      *
  646.      * Any type for which a corresponding is_<type>() function exists is
  647.      * acceptable. Additionally, fully-qualified class or interface names may
  648.      * be passed.
  649.      *
  650.      * @param string|string[] $allowedTypes One or more accepted types
  651.      *
  652.      * @return $this
  653.      *
  654.      * @throws UndefinedOptionsException If the option is undefined
  655.      * @throws AccessException           If called from a lazy option or normalizer
  656.      */
  657.     public function setAllowedTypes(string $option, string|array $allowedTypes)
  658.     {
  659.         if ($this->locked) {
  660.             throw new AccessException('Allowed types cannot be set from a lazy option or normalizer.');
  661.         }
  663.         if (!isset($this->defined[$option])) {
  664.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  665.         }
  667.         $this->allowedTypes[$option] = (array) $allowedTypes;
  669.         // Make sure the option is processed
  670.         unset($this->resolved[$option]);
  672.         return $this;
  673.     }
  675.     /**
  676.      * Adds allowed types for an option.
  677.      *
  678.      * The types are merged with the allowed types defined previously.
  679.      *
  680.      * Any type for which a corresponding is_<type>() function exists is
  681.      * acceptable. Additionally, fully-qualified class or interface names may
  682.      * be passed.
  683.      *
  684.      * @param string|string[] $allowedTypes One or more accepted types
  685.      *
  686.      * @return $this
  687.      *
  688.      * @throws UndefinedOptionsException If the option is undefined
  689.      * @throws AccessException           If called from a lazy option or normalizer
  690.      */
  691.     public function addAllowedTypes(string $option, string|array $allowedTypes)
  692.     {
  693.         if ($this->locked) {
  694.             throw new AccessException('Allowed types cannot be added from a lazy option or normalizer.');
  695.         }
  697.         if (!isset($this->defined[$option])) {
  698.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  699.         }
  701.         if (!isset($this->allowedTypes[$option])) {
  702.             $this->allowedTypes[$option] = (array) $allowedTypes;
  703.         } else {
  704.             $this->allowedTypes[$option] = array_merge($this->allowedTypes[$option], (array) $allowedTypes);
  705.         }
  707.         // Make sure the option is processed
  708.         unset($this->resolved[$option]);
  710.         return $this;
  711.     }
  713.     /**
  714.      * Defines an option configurator with the given name.
  715.      */
  716.     public function define(string $option): OptionConfigurator
  717.     {
  718.         if (isset($this->defined[$option])) {
  719.             throw new OptionDefinitionException(sprintf('The option "%s" is already defined.', $option));
  720.         }
  722.         return new OptionConfigurator($option, $this);
  723.     }
  725.     /**
  726.      * Sets an info message for an option.
  727.      *
  728.      * @return $this
  729.      *
  730.      * @throws UndefinedOptionsException If the option is undefined
  731.      * @throws AccessException           If called from a lazy option or normalizer
  732.      */
  733.     public function setInfo(string $option, string $info): static
  734.     {
  735.         if ($this->locked) {
  736.             throw new AccessException('The Info message cannot be set from a lazy option or normalizer.');
  737.         }
  739.         if (!isset($this->defined[$option])) {
  740.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  741.         }
  743.         $this->info[$option] = $info;
  745.         return $this;
  746.     }
  748.     /**
  749.      * Gets the info message for an option.
  750.      */
  751.     public function getInfo(string $option): ?string
  752.     {
  753.         if (!isset($this->defined[$option])) {
  754.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  755.         }
  757.         return $this->info[$option] ?? null;
  758.     }
  760.     /**
  761.      * Marks the whole options definition as array prototype.
  762.      *
  763.      * @return $this
  764.      *
  765.      * @throws AccessException If called from a lazy option, a normalizer or a root definition
  766.      */
  767.     public function setPrototype(bool $prototype): static
  768.     {
  769.         if ($this->locked) {
  770.             throw new AccessException('The prototype property cannot be set from a lazy option or normalizer.');
  771.         }
  773.         if (null === $this->prototype && $prototype) {
  774.             throw new AccessException('The prototype property cannot be set from a root definition.');
  775.         }
  777.         $this->prototype = $prototype;
  779.         return $this;
  780.     }
  782.     public function isPrototype(): bool
  783.     {
  784.         return $this->prototype ?? false;
  785.     }
  787.     /**
  788.      * Removes the option with the given name.
  789.      *
  790.      * Undefined options are ignored.
  791.      *
  792.      * @param string|string[] $optionNames One or more option names
  793.      *
  794.      * @return $this
  795.      *
  796.      * @throws AccessException If called from a lazy option or normalizer
  797.      */
  798.     public function remove(string|array $optionNames): static
  799.     {
  800.         if ($this->locked) {
  801.             throw new AccessException('Options cannot be removed from a lazy option or normalizer.');
  802.         }
  804.         foreach ((array) $optionNames as $option) {
  805.             unset($this->defined[$option], $this->defaults[$option], $this->required[$option], $this->resolved[$option]);
  806.             unset($this->lazy[$option], $this->normalizers[$option], $this->allowedTypes[$option], $this->allowedValues[$option], $this->info[$option]);
  807.         }
  809.         return $this;
  810.     }
  812.     /**
  813.      * Removes all options.
  814.      *
  815.      * @return $this
  816.      *
  817.      * @throws AccessException If called from a lazy option or normalizer
  818.      */
  819.     public function clear(): static
  820.     {
  821.         if ($this->locked) {
  822.             throw new AccessException('Options cannot be cleared from a lazy option or normalizer.');
  823.         }
  825.         $this->defined = [];
  826.         $this->defaults = [];
  827.         $this->nested = [];
  828.         $this->required = [];
  829.         $this->resolved = [];
  830.         $this->lazy = [];
  831.         $this->normalizers = [];
  832.         $this->allowedTypes = [];
  833.         $this->allowedValues = [];
  834.         $this->deprecated = [];
  835.         $this->info = [];
  837.         return $this;
  838.     }
  840.     /**
  841.      * Merges options with the default values stored in the container and
  842.      * validates them.
  843.      *
  844.      * Exceptions are thrown if:
  845.      *
  846.      *  - Undefined options are passed;
  847.      *  - Required options are missing;
  848.      *  - Options have invalid types;
  849.      *  - Options have invalid values.
  850.      *
  851.      * @throws UndefinedOptionsException If an option name is undefined
  852.      * @throws InvalidOptionsException   If an option doesn't fulfill the
  853.      *                                   specified validation rules
  854.      * @throws MissingOptionsException   If a required option is missing
  855.      * @throws OptionDefinitionException If there is a cyclic dependency between
  856.      *                                   lazy options and/or normalizers
  857.      * @throws NoSuchOptionException     If a lazy option reads an unavailable option
  858.      * @throws AccessException           If called from a lazy option or normalizer
  859.      */
  860.     public function resolve(array $options = []): array
  861.     {
  862.         if ($this->locked) {
  863.             throw new AccessException('Options cannot be resolved from a lazy option or normalizer.');
  864.         }
  866.         // Allow this method to be called multiple times
  867.         $clone = clone $this;
  869.         // Make sure that no unknown options are passed
  870.         $diff = $this->ignoreUndefined ? [] : array_diff_key($options, $clone->defined);
  872.         if (\count($diff) > 0) {
  873.             ksort($clone->defined);
  874.             ksort($diff);
  876.             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))));
  877.         }
  879.         // Override options set by the user
  880.         foreach ($options as $option => $value) {
  881.             if ($this->ignoreUndefined && !isset($clone->defined[$option])) {
  882.                 continue;
  883.             }
  885.             $clone->given[$option] = true;
  886.             $clone->defaults[$option] = $value;
  887.             unset($clone->resolved[$option], $clone->lazy[$option]);
  888.         }
  890.         // Check whether any required option is missing
  891.         $diff = array_diff_key($clone->required, $clone->defaults);
  893.         if (\count($diff) > 0) {
  894.             ksort($diff);
  896.             throw new MissingOptionsException(sprintf(\count($diff) > 1 ? 'The required options "%s" are missing.' : 'The required option "%s" is missing.', $this->formatOptions(array_keys($diff))));
  897.         }
  899.         // Lock the container
  900.         $clone->locked = true;
  902.         // Now process the individual options. Use offsetGet(), which resolves
  903.         // the option itself and any options that the option depends on
  904.         foreach ($clone->defaults as $option => $_) {
  905.             $clone->offsetGet($option);
  906.         }
  908.         return $clone->resolved;
  909.     }
  911.     /**
  912.      * Returns the resolved value of an option.
  913.      *
  914.      * @param bool $triggerDeprecation Whether to trigger the deprecation or not (true by default)
  915.      *
  916.      * @throws AccessException           If accessing this method outside of
  917.      *                                   {@link resolve()}
  918.      * @throws NoSuchOptionException     If the option is not set
  919.      * @throws InvalidOptionsException   If the option doesn't fulfill the
  920.      *                                   specified validation rules
  921.      * @throws OptionDefinitionException If there is a cyclic dependency between
  922.      *                                   lazy options and/or normalizers
  923.      */
  924.     public function offsetGet(mixed $option, bool $triggerDeprecation = true): mixed
  925.     {
  926.         if (!$this->locked) {
  927.             throw new AccessException('Array access is only supported within closures of lazy options and normalizers.');
  928.         }
  930.         // Shortcut for resolved options
  931.         if (isset($this->resolved[$option]) || \array_key_exists($option, $this->resolved)) {
  932.             if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || $this->calling) && \is_string($this->deprecated[$option]['message'])) {
  933.                 trigger_deprecation($this->deprecated[$option]['package'], $this->deprecated[$option]['version'], strtr($this->deprecated[$option]['message'], ['%name%' => $option]));
  934.             }
  936.             return $this->resolved[$option];
  937.         }
  939.         // Check whether the option is set at all
  940.         if (!isset($this->defaults[$option]) && !\array_key_exists($option, $this->defaults)) {
  941.             if (!isset($this->defined[$option])) {
  942.                 throw new NoSuchOptionException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  943.             }
  945.             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])));
  946.         }
  948.         $value = $this->defaults[$option];
  950.         // Resolve the option if it is a nested definition
  951.         if (isset($this->nested[$option])) {
  952.             // If the closure is already being called, we have a cyclic dependency
  953.             if (isset($this->calling[$option])) {
  954.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  955.             }
  957.             if (!\is_array($value)) {
  958.                 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)));
  959.             }
  961.             // The following section must be protected from cyclic calls.
  962.             $this->calling[$option] = true;
  963.             try {
  964.                 $resolver = new self();
  965.                 $resolver->prototype = false;
  966.                 $resolver->parentsOptions = $this->parentsOptions;
  967.                 $resolver->parentsOptions[] = $option;
  968.                 foreach ($this->nested[$option] as $closure) {
  969.                     $closure($resolver, $this);
  970.                 }
  972.                 if ($resolver->prototype) {
  973.                     $values = [];
  974.                     foreach ($value as $index => $prototypeValue) {
  975.                         if (!\is_array($prototypeValue)) {
  976.                             throw new InvalidOptionsException(sprintf('The value of the option "%s" is expected to be of type array of array, but is of type array of "%s".', $this->formatOptions([$option]), get_debug_type($prototypeValue)));
  977.                         }
  979.                         $resolver->prototypeIndex = $index;
  980.                         $values[$index] = $resolver->resolve($prototypeValue);
  981.                     }
  982.                     $value = $values;
  983.                 } else {
  984.                     $value = $resolver->resolve($value);
  985.                 }
  986.             } finally {
  987.                 $resolver->prototypeIndex = null;
  988.                 unset($this->calling[$option]);
  989.             }
  990.         }
  992.         // Resolve the option if the default value is lazily evaluated
  993.         if (isset($this->lazy[$option])) {
  994.             // If the closure is already being called, we have a cyclic
  995.             // dependency
  996.             if (isset($this->calling[$option])) {
  997.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  998.             }
  1000.             // The following section must be protected from cyclic
  1001.             // calls. Set $calling for the current $option to detect a cyclic
  1002.             // dependency
  1003.             // BEGIN
  1004.             $this->calling[$option] = true;
  1005.             try {
  1006.                 foreach ($this->lazy[$option] as $closure) {
  1007.                     $value = $closure($this, $value);
  1008.                 }
  1009.             } finally {
  1010.                 unset($this->calling[$option]);
  1011.             }
  1012.             // END
  1013.         }
  1015.         // Validate the type of the resolved option
  1016.         if (isset($this->allowedTypes[$option])) {
  1017.             $valid = true;
  1018.             $invalidTypes = [];
  1020.             foreach ($this->allowedTypes[$option] as $type) {
  1021.                 if ($valid = $this->verifyTypes($type, $value, $invalidTypes)) {
  1022.                     break;
  1023.                 }
  1024.             }
  1026.             if (!$valid) {
  1027.                 $fmtActualValue = $this->formatValue($value);
  1028.                 $fmtAllowedTypes = implode('" or "', $this->allowedTypes[$option]);
  1029.                 $fmtProvidedTypes = implode('|', array_keys($invalidTypes));
  1030.                 $allowedContainsArrayType = \count(array_filter($this->allowedTypes[$option], static fn ($item) => str_ends_with($item, '[]'))) > 0;
  1032.                 if (\is_array($value) && $allowedContainsArrayType) {
  1033.                     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));
  1034.                 }
  1036.                 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));
  1037.             }
  1038.         }
  1040.         // Validate the value of the resolved option
  1041.         if (isset($this->allowedValues[$option])) {
  1042.             $success = false;
  1043.             $printableAllowedValues = [];
  1045.             foreach ($this->allowedValues[$option] as $allowedValue) {
  1046.                 if ($allowedValue instanceof \Closure) {
  1047.                     if ($allowedValue($value)) {
  1048.                         $success = true;
  1049.                         break;
  1050.                     }
  1052.                     // Don't include closures in the exception message
  1053.                     continue;
  1054.                 }
  1056.                 if ($value === $allowedValue) {
  1057.                     $success = true;
  1058.                     break;
  1059.                 }
  1061.                 $printableAllowedValues[] = $allowedValue;
  1062.             }
  1064.             if (!$success) {
  1065.                 $message = sprintf(
  1066.                     'The option "%s" with value %s is invalid.',
  1067.                     $option,
  1068.                     $this->formatValue($value)
  1069.                 );
  1071.                 if (\count($printableAllowedValues) > 0) {
  1072.                     $message .= sprintf(
  1073.                         ' Accepted values are: %s.',
  1074.                         $this->formatValues($printableAllowedValues)
  1075.                     );
  1076.                 }
  1078.                 if (isset($this->info[$option])) {
  1079.                     $message .= sprintf(' Info: %s.', $this->info[$option]);
  1080.                 }
  1082.                 throw new InvalidOptionsException($message);
  1083.             }
  1084.         }
  1086.         // Check whether the option is deprecated
  1087.         // and it is provided by the user or is being called from a lazy evaluation
  1088.         if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || ($this->calling && \is_string($this->deprecated[$option]['message'])))) {
  1089.             $deprecation = $this->deprecated[$option];
  1090.             $message = $this->deprecated[$option]['message'];
  1092.             if ($message instanceof \Closure) {
  1093.                 // If the closure is already being called, we have a cyclic dependency
  1094.                 if (isset($this->calling[$option])) {
  1095.                     throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  1096.                 }
  1098.                 $this->calling[$option] = true;
  1099.                 try {
  1100.                     if (!\is_string($message = $message($this, $value))) {
  1101.                         throw new InvalidOptionsException(sprintf('Invalid type for deprecation message, expected string but got "%s", return an empty string to ignore.', get_debug_type($message)));
  1102.                     }
  1103.                 } finally {
  1104.                     unset($this->calling[$option]);
  1105.                 }
  1106.             }
  1108.             if ('' !== $message) {
  1109.                 trigger_deprecation($deprecation['package'], $deprecation['version'], strtr($message, ['%name%' => $option]));
  1110.             }
  1111.         }
  1113.         // Normalize the validated option
  1114.         if (isset($this->normalizers[$option])) {
  1115.             // If the closure is already being called, we have a cyclic
  1116.             // dependency
  1117.             if (isset($this->calling[$option])) {
  1118.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  1119.             }
  1121.             // The following section must be protected from cyclic
  1122.             // calls. Set $calling for the current $option to detect a cyclic
  1123.             // dependency
  1124.             // BEGIN
  1125.             $this->calling[$option] = true;
  1126.             try {
  1127.                 foreach ($this->normalizers[$option] as $normalizer) {
  1128.                     $value = $normalizer($this, $value);
  1129.                 }
  1130.             } finally {
  1131.                 unset($this->calling[$option]);
  1132.             }
  1133.             // END
  1134.         }
  1136.         // Mark as resolved
  1137.         $this->resolved[$option] = $value;
  1139.         return $value;
  1140.     }
  1142.     private function verifyTypes(string $type, mixed $value, array &$invalidTypes, int $level = 0): bool
  1143.     {
  1144.         if (\is_array($value) && str_ends_with($type, '[]')) {
  1145.             $type = substr($type, 0, -2);
  1146.             $valid = true;
  1148.             foreach ($value as $val) {
  1149.                 if (!$this->verifyTypes($type, $val, $invalidTypes, $level + 1)) {
  1150.                     $valid = false;
  1151.                 }
  1152.             }
  1154.             return $valid;
  1155.         }
  1157.         if (('null' === $type && null === $value) || (isset(self::VALIDATION_FUNCTIONS[$type]) ? self::VALIDATION_FUNCTIONS[$type]($value) : $value instanceof $type)) {
  1158.             return true;
  1159.         }
  1161.         if (!$invalidTypes || $level > 0) {
  1162.             $invalidTypes[get_debug_type($value)] = true;
  1163.         }
  1165.         return false;
  1166.     }
  1168.     /**
  1169.      * Returns whether a resolved option with the given name exists.
  1170.      *
  1171.      * @throws AccessException If accessing this method outside of {@link resolve()}
  1172.      *
  1173.      * @see \ArrayAccess::offsetExists()
  1174.      */
  1175.     public function offsetExists(mixed $option): bool
  1176.     {
  1177.         if (!$this->locked) {
  1178.             throw new AccessException('Array access is only supported within closures of lazy options and normalizers.');
  1179.         }
  1181.         return \array_key_exists($option, $this->defaults);
  1182.     }
  1184.     /**
  1185.      * Not supported.
  1186.      *
  1187.      * @throws AccessException
  1188.      */
  1189.     public function offsetSet(mixed $option, mixed $value): void
  1190.     {
  1191.         throw new AccessException('Setting options via array access is not supported. Use setDefault() instead.');
  1192.     }
  1194.     /**
  1195.      * Not supported.
  1196.      *
  1197.      * @throws AccessException
  1198.      */
  1199.     public function offsetUnset(mixed $option): void
  1200.     {
  1201.         throw new AccessException('Removing options via array access is not supported. Use remove() instead.');
  1202.     }
  1204.     /**
  1205.      * Returns the number of set options.
  1206.      *
  1207.      * This may be only a subset of the defined options.
  1208.      *
  1209.      * @throws AccessException If accessing this method outside of {@link resolve()}
  1210.      *
  1211.      * @see \Countable::count()
  1212.      */
  1213.     public function count(): int
  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.      * Sets whether ignore undefined options.
  1224.      *
  1225.      * @return $this
  1226.      */
  1227.     public function setIgnoreUndefined(bool $ignore = true): static
  1228.     {
  1229.         $this->ignoreUndefined = $ignore;
  1231.         return $this;
  1232.     }
  1234.     /**
  1235.      * Returns a string representation of the value.
  1236.      *
  1237.      * This method returns the equivalent PHP tokens for most scalar types
  1238.      * (i.e. "false" for false, "1" for 1 etc.). Strings are always wrapped
  1239.      * in double quotes (").
  1240.      */
  1241.     private function formatValue(mixed $value): string
  1242.     {
  1243.         if (\is_object($value)) {
  1244.             return $value::class;
  1245.         }
  1247.         if (\is_array($value)) {
  1248.             return 'array';
  1249.         }
  1251.         if (\is_string($value)) {
  1252.             return '"'.$value.'"';
  1253.         }
  1255.         if (\is_resource($value)) {
  1256.             return 'resource';
  1257.         }
  1259.         if (null === $value) {
  1260.             return 'null';
  1261.         }
  1263.         if (false === $value) {
  1264.             return 'false';
  1265.         }
  1267.         if (true === $value) {
  1268.             return 'true';
  1269.         }
  1271.         return (string) $value;
  1272.     }
  1274.     /**
  1275.      * Returns a string representation of a list of values.
  1276.      *
  1277.      * Each of the values is converted to a string using
  1278.      * {@link formatValue()}. The values are then concatenated with commas.
  1279.      *
  1280.      * @see formatValue()
  1281.      */
  1282.     private function formatValues(array $values): string
  1283.     {
  1284.         foreach ($values as $key => $value) {
  1285.             $values[$key] = $this->formatValue($value);
  1286.         }
  1288.         return implode(', ', $values);
  1289.     }
  1291.     private function formatOptions(array $options): string
  1292.     {
  1293.         if ($this->parentsOptions) {
  1294.             $prefix = array_shift($this->parentsOptions);
  1295.             if ($this->parentsOptions) {
  1296.                 $prefix .= sprintf('[%s]', implode('][', $this->parentsOptions));
  1297.             }
  1299.             if ($this->prototype && null !== $this->prototypeIndex) {
  1300.                 $prefix .= sprintf('[%s]', $this->prototypeIndex);
  1301.             }
  1303.             $options = array_map(static fn (string $option): string => sprintf('%s[%s]', $prefix, $option), $options);
  1304.         }
  1306.         return implode('", "', $options);
  1307.     }
  1309.     private function getParameterClassName(\ReflectionParameter $parameter): ?string
  1310.     {
  1311.         if (!($type = $parameter->getType()) instanceof \ReflectionNamedType || $type->isBuiltin()) {
  1312.             return null;
  1313.         }
  1315.         return $type->getName();
  1316.     }
  1317. }