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

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