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

Open in your IDE?
  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Symfony\Component\OptionsResolver;
  14. use Symfony\Component\OptionsResolver\Exception\AccessException;
  15. use Symfony\Component\OptionsResolver\Exception\InvalidArgumentException;
  16. use Symfony\Component\OptionsResolver\Exception\InvalidOptionsException;
  17. use Symfony\Component\OptionsResolver\Exception\MissingOptionsException;
  18. use Symfony\Component\OptionsResolver\Exception\NoSuchOptionException;
  19. use Symfony\Component\OptionsResolver\Exception\OptionDefinitionException;
  20. use Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException;
  22. /**
  23.  * Validates options and merges them with default values.
  24.  *
  25.  * @author Bernhard Schussek <bschussek@gmail.com>
  26.  * @author Tobias Schultze <http://tobion.de>
  27.  */
  28. class OptionsResolver implements Options
  29. {
  30.     /**
  31.      * The names of all defined options.
  32.      */
  33.     private $defined = [];
  35.     /**
  36.      * The default option values.
  37.      */
  38.     private $defaults = [];
  40.     /**
  41.      * A list of closure for nested options.
  42.      *
  43.      * @var \Closure[][]
  44.      */
  45.     private $nested = [];
  47.     /**
  48.      * The names of required options.
  49.      */
  50.     private $required = [];
  52.     /**
  53.      * The resolved option values.
  54.      */
  55.     private $resolved = [];
  57.     /**
  58.      * A list of normalizer closures.
  59.      *
  60.      * @var \Closure[][]
  61.      */
  62.     private $normalizers = [];
  64.     /**
  65.      * A list of accepted values for each option.
  66.      */
  67.     private $allowedValues = [];
  69.     /**
  70.      * A list of accepted types for each option.
  71.      */
  72.     private $allowedTypes = [];
  74.     /**
  75.      * A list of info messages for each option.
  76.      */
  77.     private $info = [];
  79.     /**
  80.      * A list of closures for evaluating lazy options.
  81.      */
  82.     private $lazy = [];
  84.     /**
  85.      * A list of lazy options whose closure is currently being called.
  86.      *
  87.      * This list helps detecting circular dependencies between lazy options.
  88.      */
  89.     private $calling = [];
  91.     /**
  92.      * A list of deprecated options.
  93.      */
  94.     private $deprecated = [];
  96.     /**
  97.      * The list of options provided by the user.
  98.      */
  99.     private $given = [];
  101.     /**
  102.      * Whether the instance is locked for reading.
  103.      *
  104.      * Once locked, the options cannot be changed anymore. This is
  105.      * necessary in order to avoid inconsistencies during the resolving
  106.      * process. If any option is changed after being read, all evaluated
  107.      * lazy options that depend on this option would become invalid.
  108.      */
  109.     private $locked = false;
  111.     private $parentsOptions = [];
  113.     private static $typeAliases = [
  114.         'boolean' => 'bool',
  115.         'integer' => 'int',
  116.         'double' => 'float',
  117.     ];
  119.     /**
  120.      * Sets the default value of a given option.
  121.      *
  122.      * If the default value should be set based on other options, you can pass
  123.      * a closure with the following signature:
  124.      *
  125.      *     function (Options $options) {
  126.      *         // ...
  127.      *     }
  128.      *
  129.      * The closure will be evaluated when {@link resolve()} is called. The
  130.      * closure has access to the resolved values of other options through the
  131.      * passed {@link Options} instance:
  132.      *
  133.      *     function (Options $options) {
  134.      *         if (isset($options['port'])) {
  135.      *             // ...
  136.      *         }
  137.      *     }
  138.      *
  139.      * If you want to access the previously set default value, add a second
  140.      * argument to the closure's signature:
  141.      *
  142.      *     $options->setDefault('name', 'Default Name');
  143.      *
  144.      *     $options->setDefault('name', function (Options $options, $previousValue) {
  145.      *         // 'Default Name' === $previousValue
  146.      *     });
  147.      *
  148.      * This is mostly useful if the configuration of the {@link Options} object
  149.      * is spread across different locations of your code, such as base and
  150.      * sub-classes.
  151.      *
  152.      * If you want to define nested options, you can pass a closure with the
  153.      * following signature:
  154.      *
  155.      *     $options->setDefault('database', function (OptionsResolver $resolver) {
  156.      *         $resolver->setDefined(['dbname', 'host', 'port', 'user', 'pass']);
  157.      *     }
  158.      *
  159.      * To get access to the parent options, add a second argument to the closure's
  160.      * signature:
  161.      *
  162.      *     function (OptionsResolver $resolver, Options $parent) {
  163.      *         // 'default' === $parent['connection']
  164.      *     }
  165.      *
  166.      * @param string $option The name of the option
  167.      * @param mixed  $value  The default value of the option
  168.      *
  169.      * @return $this
  170.      *
  171.      * @throws AccessException If called from a lazy option or normalizer
  172.      */
  173.     public function setDefault(string $option, $value)
  174.     {
  175.         // Setting is not possible once resolving starts, because then lazy
  176.         // options could manipulate the state of the object, leading to
  177.         // inconsistent results.
  178.         if ($this->locked) {
  179.             throw new AccessException('Default values cannot be set from a lazy option or normalizer.');
  180.         }
  182.         // If an option is a closure that should be evaluated lazily, store it
  183.         // in the "lazy" property.
  184.         if ($value instanceof \Closure) {
  185.             $reflClosure = new \ReflectionFunction($value);
  186.             $params = $reflClosure->getParameters();
  188.             if (isset($params[0]) && Options::class === $this->getParameterClassName($params[0])) {
  189.                 // Initialize the option if no previous value exists
  190.                 if (!isset($this->defaults[$option])) {
  191.                     $this->defaults[$option] = null;
  192.                 }
  194.                 // Ignore previous lazy options if the closure has no second parameter
  195.                 if (!isset($this->lazy[$option]) || !isset($params[1])) {
  196.                     $this->lazy[$option] = [];
  197.                 }
  199.                 // Store closure for later evaluation
  200.                 $this->lazy[$option][] = $value;
  201.                 $this->defined[$option] = true;
  203.                 // Make sure the option is processed and is not nested anymore
  204.                 unset($this->resolved[$option], $this->nested[$option]);
  206.                 return $this;
  207.             }
  209.             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()))) {
  210.                 // Store closure for later evaluation
  211.                 $this->nested[$option][] = $value;
  212.                 $this->defaults[$option] = [];
  213.                 $this->defined[$option] = true;
  215.                 // Make sure the option is processed and is not lazy anymore
  216.                 unset($this->resolved[$option], $this->lazy[$option]);
  218.                 return $this;
  219.             }
  220.         }
  222.         // This option is not lazy nor nested anymore
  223.         unset($this->lazy[$option], $this->nested[$option]);
  225.         // Yet undefined options can be marked as resolved, because we only need
  226.         // to resolve options with lazy closures, normalizers or validation
  227.         // rules, none of which can exist for undefined options
  228.         // If the option was resolved before, update the resolved value
  229.         if (!isset($this->defined[$option]) || \array_key_exists($option, $this->resolved)) {
  230.             $this->resolved[$option] = $value;
  231.         }
  233.         $this->defaults[$option] = $value;
  234.         $this->defined[$option] = true;
  236.         return $this;
  237.     }
  239.     /**
  240.      * Sets a list of default values.
  241.      *
  242.      * @param array $defaults The default values to set
  243.      *
  244.      * @return $this
  245.      *
  246.      * @throws AccessException If called from a lazy option or normalizer
  247.      */
  248.     public function setDefaults(array $defaults)
  249.     {
  250.         foreach ($defaults as $option => $value) {
  251.             $this->setDefault($option, $value);
  252.         }
  254.         return $this;
  255.     }
  257.     /**
  258.      * Returns whether a default value is set for an option.
  259.      *
  260.      * Returns true if {@link setDefault()} was called for this option.
  261.      * An option is also considered set if it was set to null.
  262.      *
  263.      * @param string $option The option name
  264.      *
  265.      * @return bool Whether a default value is set
  266.      */
  267.     public function hasDefault(string $option)
  268.     {
  269.         return \array_key_exists($option, $this->defaults);
  270.     }
  272.     /**
  273.      * Marks one or more options as required.
  274.      *
  275.      * @param string|string[] $optionNames One or more option names
  276.      *
  277.      * @return $this
  278.      *
  279.      * @throws AccessException If called from a lazy option or normalizer
  280.      */
  281.     public function setRequired($optionNames)
  282.     {
  283.         if ($this->locked) {
  284.             throw new AccessException('Options cannot be made required from a lazy option or normalizer.');
  285.         }
  287.         foreach ((array) $optionNames as $option) {
  288.             $this->defined[$option] = true;
  289.             $this->required[$option] = true;
  290.         }
  292.         return $this;
  293.     }
  295.     /**
  296.      * Returns whether an option is required.
  297.      *
  298.      * An option is required if it was passed to {@link setRequired()}.
  299.      *
  300.      * @param string $option The name of the option
  301.      *
  302.      * @return bool Whether the option is required
  303.      */
  304.     public function isRequired(string $option)
  305.     {
  306.         return isset($this->required[$option]);
  307.     }
  309.     /**
  310.      * Returns the names of all required options.
  311.      *
  312.      * @return string[] The names of the required options
  313.      *
  314.      * @see isRequired()
  315.      */
  316.     public function getRequiredOptions()
  317.     {
  318.         return array_keys($this->required);
  319.     }
  321.     /**
  322.      * Returns whether an option is missing a default value.
  323.      *
  324.      * An option is missing if it was passed to {@link setRequired()}, but not
  325.      * to {@link setDefault()}. This option must be passed explicitly to
  326.      * {@link resolve()}, otherwise an exception will be thrown.
  327.      *
  328.      * @param string $option The name of the option
  329.      *
  330.      * @return bool Whether the option is missing
  331.      */
  332.     public function isMissing(string $option)
  333.     {
  334.         return isset($this->required[$option]) && !\array_key_exists($option, $this->defaults);
  335.     }
  337.     /**
  338.      * Returns the names of all options missing a default value.
  339.      *
  340.      * @return string[] The names of the missing options
  341.      *
  342.      * @see isMissing()
  343.      */
  344.     public function getMissingOptions()
  345.     {
  346.         return array_keys(array_diff_key($this->required, $this->defaults));
  347.     }
  349.     /**
  350.      * Defines a valid option name.
  351.      *
  352.      * Defines an option name without setting a default value. The option will
  353.      * be accepted when passed to {@link resolve()}. When not passed, the
  354.      * option will not be included in the resolved options.
  355.      *
  356.      * @param string|string[] $optionNames One or more option names
  357.      *
  358.      * @return $this
  359.      *
  360.      * @throws AccessException If called from a lazy option or normalizer
  361.      */
  362.     public function setDefined($optionNames)
  363.     {
  364.         if ($this->locked) {
  365.             throw new AccessException('Options cannot be defined from a lazy option or normalizer.');
  366.         }
  368.         foreach ((array) $optionNames as $option) {
  369.             $this->defined[$option] = true;
  370.         }
  372.         return $this;
  373.     }
  375.     /**
  376.      * Returns whether an option is defined.
  377.      *
  378.      * Returns true for any option passed to {@link setDefault()},
  379.      * {@link setRequired()} or {@link setDefined()}.
  380.      *
  381.      * @param string $option The option name
  382.      *
  383.      * @return bool Whether the option is defined
  384.      */
  385.     public function isDefined(string $option)
  386.     {
  387.         return isset($this->defined[$option]);
  388.     }
  390.     /**
  391.      * Returns the names of all defined options.
  392.      *
  393.      * @return string[] The names of the defined options
  394.      *
  395.      * @see isDefined()
  396.      */
  397.     public function getDefinedOptions()
  398.     {
  399.         return array_keys($this->defined);
  400.     }
  402.     public function isNested(string $option): bool
  403.     {
  404.         return isset($this->nested[$option]);
  405.     }
  407.     /**
  408.      * Deprecates an option, allowed types or values.
  409.      *
  410.      * Instead of passing the message, you may also pass a closure with the
  411.      * following signature:
  412.      *
  413.      *     function (Options $options, $value): string {
  414.      *         // ...
  415.      *     }
  416.      *
  417.      * The closure receives the value as argument and should return a string.
  418.      * Return an empty string to ignore the option deprecation.
  419.      *
  420.      * The closure is invoked when {@link resolve()} is called. The parameter
  421.      * passed to the closure is the value of the option after validating it
  422.      * and before normalizing it.
  423.      *
  424.      * @param string          $package The name of the composer package that is triggering the deprecation
  425.      * @param string          $version The version of the package that introduced the deprecation
  426.      * @param string|\Closure $message The deprecation message to use
  427.      */
  428.     public function setDeprecated(string $option/*, string $package, string $version, $message = 'The option "%name%" is deprecated.' */): self
  429.     {
  430.         if ($this->locked) {
  431.             throw new AccessException('Options cannot be deprecated from a lazy option or normalizer.');
  432.         }
  434.         if (!isset($this->defined[$option])) {
  435.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist, defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  436.         }
  438.         $args = \func_get_args();
  440.         if (\func_num_args() < 3) {
  441.             trigger_deprecation('symfony/options-resolver', '5.1', 'The signature of method "%s()" requires 2 new arguments: "string $package, string $version", not defining them is deprecated.', __METHOD__);
  443.             $message = $args[1] ?? 'The option "%name%" is deprecated.';
  444.             $package = $version = '';
  445.         } else {
  446.             $package = $args[1];
  447.             $version = $args[2];
  448.             $message = $args[3] ?? 'The option "%name%" is deprecated.';
  449.         }
  451.         if (!\is_string($message) && !$message instanceof \Closure) {
  452.             throw new InvalidArgumentException(sprintf('Invalid type for deprecation message argument, expected string or \Closure, but got "%s".', get_debug_type($message)));
  453.         }
  455.         // ignore if empty string
  456.         if ('' === $message) {
  457.             return $this;
  458.         }
  460.         $this->deprecated[$option] = [
  461.             'package' => $package,
  462.             'version' => $version,
  463.             'message' => $message,
  464.         ];
  466.         // Make sure the option is processed
  467.         unset($this->resolved[$option]);
  469.         return $this;
  470.     }
  472.     public function isDeprecated(string $option): bool
  473.     {
  474.         return isset($this->deprecated[$option]);
  475.     }
  477.     /**
  478.      * Sets the normalizer for an option.
  479.      *
  480.      * The normalizer should be a closure with the following signature:
  481.      *
  482.      *     function (Options $options, $value) {
  483.      *         // ...
  484.      *     }
  485.      *
  486.      * The closure is invoked when {@link resolve()} is called. The closure
  487.      * has access to the resolved values of other options through the passed
  488.      * {@link Options} instance.
  489.      *
  490.      * The second parameter passed to the closure is the value of
  491.      * the option.
  492.      *
  493.      * The resolved option value is set to the return value of the closure.
  494.      *
  495.      * @param string   $option     The option name
  496.      * @param \Closure $normalizer The normalizer
  497.      *
  498.      * @return $this
  499.      *
  500.      * @throws UndefinedOptionsException If the option is undefined
  501.      * @throws AccessException           If called from a lazy option or normalizer
  502.      */
  503.     public function setNormalizer(string $option, \Closure $normalizer)
  504.     {
  505.         if ($this->locked) {
  506.             throw new AccessException('Normalizers cannot be set from a lazy option or normalizer.');
  507.         }
  509.         if (!isset($this->defined[$option])) {
  510.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  511.         }
  513.         $this->normalizers[$option] = [$normalizer];
  515.         // Make sure the option is processed
  516.         unset($this->resolved[$option]);
  518.         return $this;
  519.     }
  521.     /**
  522.      * Adds a normalizer for an option.
  523.      *
  524.      * The normalizer should be a closure with the following signature:
  525.      *
  526.      *     function (Options $options, $value): mixed {
  527.      *         // ...
  528.      *     }
  529.      *
  530.      * The closure is invoked when {@link resolve()} is called. The closure
  531.      * has access to the resolved values of other options through the passed
  532.      * {@link Options} instance.
  533.      *
  534.      * The second parameter passed to the closure is the value of
  535.      * the option.
  536.      *
  537.      * The resolved option value is set to the return value of the closure.
  538.      *
  539.      * @param string   $option       The option name
  540.      * @param \Closure $normalizer   The normalizer
  541.      * @param bool     $forcePrepend If set to true, prepend instead of appending
  542.      *
  543.      * @return $this
  544.      *
  545.      * @throws UndefinedOptionsException If the option is undefined
  546.      * @throws AccessException           If called from a lazy option or normalizer
  547.      */
  548.     public function addNormalizer(string $option, \Closure $normalizer, bool $forcePrepend = false): self
  549.     {
  550.         if ($this->locked) {
  551.             throw new AccessException('Normalizers cannot be set from a lazy option or normalizer.');
  552.         }
  554.         if (!isset($this->defined[$option])) {
  555.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  556.         }
  558.         if ($forcePrepend) {
  559.             $this->normalizers[$option] = $this->normalizers[$option] ?? [];
  560.             array_unshift($this->normalizers[$option], $normalizer);
  561.         } else {
  562.             $this->normalizers[$option][] = $normalizer;
  563.         }
  565.         // Make sure the option is processed
  566.         unset($this->resolved[$option]);
  568.         return $this;
  569.     }
  571.     /**
  572.      * Sets allowed values for an option.
  573.      *
  574.      * Instead of passing values, you may also pass a closures with the
  575.      * following signature:
  576.      *
  577.      *     function ($value) {
  578.      *         // return true or false
  579.      *     }
  580.      *
  581.      * The closure receives the value as argument and should return true to
  582.      * accept the value and false to reject the value.
  583.      *
  584.      * @param string $option        The option name
  585.      * @param mixed  $allowedValues One or more acceptable values/closures
  586.      *
  587.      * @return $this
  588.      *
  589.      * @throws UndefinedOptionsException If the option is undefined
  590.      * @throws AccessException           If called from a lazy option or normalizer
  591.      */
  592.     public function setAllowedValues(string $option, $allowedValues)
  593.     {
  594.         if ($this->locked) {
  595.             throw new AccessException('Allowed values cannot be set from a lazy option or normalizer.');
  596.         }
  598.         if (!isset($this->defined[$option])) {
  599.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  600.         }
  602.         $this->allowedValues[$option] = \is_array($allowedValues) ? $allowedValues : [$allowedValues];
  604.         // Make sure the option is processed
  605.         unset($this->resolved[$option]);
  607.         return $this;
  608.     }
  610.     /**
  611.      * Adds allowed values for an option.
  612.      *
  613.      * The values are merged with the allowed values defined previously.
  614.      *
  615.      * Instead of passing values, you may also pass a closures with the
  616.      * following signature:
  617.      *
  618.      *     function ($value) {
  619.      *         // return true or false
  620.      *     }
  621.      *
  622.      * The closure receives the value as argument and should return true to
  623.      * accept the value and false to reject the value.
  624.      *
  625.      * @param string $option        The option name
  626.      * @param mixed  $allowedValues One or more acceptable values/closures
  627.      *
  628.      * @return $this
  629.      *
  630.      * @throws UndefinedOptionsException If the option is undefined
  631.      * @throws AccessException           If called from a lazy option or normalizer
  632.      */
  633.     public function addAllowedValues(string $option, $allowedValues)
  634.     {
  635.         if ($this->locked) {
  636.             throw new AccessException('Allowed values cannot be added from a lazy option or normalizer.');
  637.         }
  639.         if (!isset($this->defined[$option])) {
  640.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  641.         }
  643.         if (!\is_array($allowedValues)) {
  644.             $allowedValues = [$allowedValues];
  645.         }
  647.         if (!isset($this->allowedValues[$option])) {
  648.             $this->allowedValues[$option] = $allowedValues;
  649.         } else {
  650.             $this->allowedValues[$option] = array_merge($this->allowedValues[$option], $allowedValues);
  651.         }
  653.         // Make sure the option is processed
  654.         unset($this->resolved[$option]);
  656.         return $this;
  657.     }
  659.     /**
  660.      * Sets allowed types for an option.
  661.      *
  662.      * Any type for which a corresponding is_<type>() function exists is
  663.      * acceptable. Additionally, fully-qualified class or interface names may
  664.      * be passed.
  665.      *
  666.      * @param string          $option       The option name
  667.      * @param string|string[] $allowedTypes One or more accepted types
  668.      *
  669.      * @return $this
  670.      *
  671.      * @throws UndefinedOptionsException If the option is undefined
  672.      * @throws AccessException           If called from a lazy option or normalizer
  673.      */
  674.     public function setAllowedTypes(string $option, $allowedTypes)
  675.     {
  676.         if ($this->locked) {
  677.             throw new AccessException('Allowed types cannot be set from a lazy option or normalizer.');
  678.         }
  680.         if (!isset($this->defined[$option])) {
  681.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  682.         }
  684.         $this->allowedTypes[$option] = (array) $allowedTypes;
  686.         // Make sure the option is processed
  687.         unset($this->resolved[$option]);
  689.         return $this;
  690.     }
  692.     /**
  693.      * Adds allowed types for an option.
  694.      *
  695.      * The types are merged with the allowed types defined previously.
  696.      *
  697.      * Any type for which a corresponding is_<type>() function exists is
  698.      * acceptable. Additionally, fully-qualified class or interface names may
  699.      * be passed.
  700.      *
  701.      * @param string          $option       The option name
  702.      * @param string|string[] $allowedTypes One or more accepted types
  703.      *
  704.      * @return $this
  705.      *
  706.      * @throws UndefinedOptionsException If the option is undefined
  707.      * @throws AccessException           If called from a lazy option or normalizer
  708.      */
  709.     public function addAllowedTypes(string $option, $allowedTypes)
  710.     {
  711.         if ($this->locked) {
  712.             throw new AccessException('Allowed types cannot be added from a lazy option or normalizer.');
  713.         }
  715.         if (!isset($this->defined[$option])) {
  716.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  717.         }
  719.         if (!isset($this->allowedTypes[$option])) {
  720.             $this->allowedTypes[$option] = (array) $allowedTypes;
  721.         } else {
  722.             $this->allowedTypes[$option] = array_merge($this->allowedTypes[$option], (array) $allowedTypes);
  723.         }
  725.         // Make sure the option is processed
  726.         unset($this->resolved[$option]);
  728.         return $this;
  729.     }
  731.     /**
  732.      * Defines an option configurator with the given name.
  733.      */
  734.     public function define(string $option): OptionConfigurator
  735.     {
  736.         if (isset($this->defined[$option])) {
  737.             throw new OptionDefinitionException(sprintf('The option "%s" is already defined.', $option));
  738.         }
  740.         return new OptionConfigurator($option, $this);
  741.     }
  743.     /**
  744.      * Sets an info message for an option.
  745.      *
  746.      * @return $this
  747.      *
  748.      * @throws UndefinedOptionsException If the option is undefined
  749.      * @throws AccessException           If called from a lazy option or normalizer
  750.      */
  751.     public function setInfo(string $option, string $info): self
  752.     {
  753.         if ($this->locked) {
  754.             throw new AccessException('The Info message cannot be set from a lazy option or normalizer.');
  755.         }
  757.         if (!isset($this->defined[$option])) {
  758.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  759.         }
  761.         $this->info[$option] = $info;
  763.         return $this;
  764.     }
  766.     /**
  767.      * Gets the info message for an option.
  768.      */
  769.     public function getInfo(string $option): ?string
  770.     {
  771.         if (!isset($this->defined[$option])) {
  772.             throw new UndefinedOptionsException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  773.         }
  775.         return $this->info[$option] ?? null;
  776.     }
  778.     /**
  779.      * Removes the option with the given name.
  780.      *
  781.      * Undefined options are ignored.
  782.      *
  783.      * @param string|string[] $optionNames One or more option names
  784.      *
  785.      * @return $this
  786.      *
  787.      * @throws AccessException If called from a lazy option or normalizer
  788.      */
  789.     public function remove($optionNames)
  790.     {
  791.         if ($this->locked) {
  792.             throw new AccessException('Options cannot be removed from a lazy option or normalizer.');
  793.         }
  795.         foreach ((array) $optionNames as $option) {
  796.             unset($this->defined[$option], $this->defaults[$option], $this->required[$option], $this->resolved[$option]);
  797.             unset($this->lazy[$option], $this->normalizers[$option], $this->allowedTypes[$option], $this->allowedValues[$option], $this->info[$option]);
  798.         }
  800.         return $this;
  801.     }
  803.     /**
  804.      * Removes all options.
  805.      *
  806.      * @return $this
  807.      *
  808.      * @throws AccessException If called from a lazy option or normalizer
  809.      */
  810.     public function clear()
  811.     {
  812.         if ($this->locked) {
  813.             throw new AccessException('Options cannot be cleared from a lazy option or normalizer.');
  814.         }
  816.         $this->defined = [];
  817.         $this->defaults = [];
  818.         $this->nested = [];
  819.         $this->required = [];
  820.         $this->resolved = [];
  821.         $this->lazy = [];
  822.         $this->normalizers = [];
  823.         $this->allowedTypes = [];
  824.         $this->allowedValues = [];
  825.         $this->deprecated = [];
  826.         $this->info = [];
  828.         return $this;
  829.     }
  831.     /**
  832.      * Merges options with the default values stored in the container and
  833.      * validates them.
  834.      *
  835.      * Exceptions are thrown if:
  836.      *
  837.      *  - Undefined options are passed;
  838.      *  - Required options are missing;
  839.      *  - Options have invalid types;
  840.      *  - Options have invalid values.
  841.      *
  842.      * @param array $options A map of option names to values
  843.      *
  844.      * @return array The merged and validated options
  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 = [])
  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 string $option             The option name
  906.      * @param bool   $triggerDeprecation Whether to trigger the deprecation or not (true by default)
  907.      *
  908.      * @return mixed The option value
  909.      *
  910.      * @throws AccessException           If accessing this method outside of
  911.      *                                   {@link resolve()}
  912.      * @throws NoSuchOptionException     If the option is not set
  913.      * @throws InvalidOptionsException   If the option doesn't fulfill the
  914.      *                                   specified validation rules
  915.      * @throws OptionDefinitionException If there is a cyclic dependency between
  916.      *                                   lazy options and/or normalizers
  917.      */
  918.     public function offsetGet($option, bool $triggerDeprecation = true)
  919.     {
  920.         if (!$this->locked) {
  921.             throw new AccessException('Array access is only supported within closures of lazy options and normalizers.');
  922.         }
  924.         // Shortcut for resolved options
  925.         if (isset($this->resolved[$option]) || \array_key_exists($option, $this->resolved)) {
  926.             if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || $this->calling) && \is_string($this->deprecated[$option]['message'])) {
  927.                 trigger_deprecation($this->deprecated[$option]['package'], $this->deprecated[$option]['version'], strtr($this->deprecated[$option]['message'], ['%name%' => $option]));
  928.             }
  930.             return $this->resolved[$option];
  931.         }
  933.         // Check whether the option is set at all
  934.         if (!isset($this->defaults[$option]) && !\array_key_exists($option, $this->defaults)) {
  935.             if (!isset($this->defined[$option])) {
  936.                 throw new NoSuchOptionException(sprintf('The option "%s" does not exist. Defined options are: "%s".', $this->formatOptions([$option]), implode('", "', array_keys($this->defined))));
  937.             }
  939.             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])));
  940.         }
  942.         $value = $this->defaults[$option];
  944.         // Resolve the option if it is a nested definition
  945.         if (isset($this->nested[$option])) {
  946.             // If the closure is already being called, we have a cyclic dependency
  947.             if (isset($this->calling[$option])) {
  948.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  949.             }
  951.             if (!\is_array($value)) {
  952.                 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)));
  953.             }
  955.             // The following section must be protected from cyclic calls.
  956.             $this->calling[$option] = true;
  957.             try {
  958.                 $resolver = new self();
  959.                 $resolver->parentsOptions = $this->parentsOptions;
  960.                 $resolver->parentsOptions[] = $option;
  961.                 foreach ($this->nested[$option] as $closure) {
  962.                     $closure($resolver, $this);
  963.                 }
  964.                 $value = $resolver->resolve($value);
  965.             } finally {
  966.                 unset($this->calling[$option]);
  967.             }
  968.         }
  970.         // Resolve the option if the default value is lazily evaluated
  971.         if (isset($this->lazy[$option])) {
  972.             // If the closure is already being called, we have a cyclic
  973.             // dependency
  974.             if (isset($this->calling[$option])) {
  975.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  976.             }
  978.             // The following section must be protected from cyclic
  979.             // calls. Set $calling for the current $option to detect a cyclic
  980.             // dependency
  981.             // BEGIN
  982.             $this->calling[$option] = true;
  983.             try {
  984.                 foreach ($this->lazy[$option] as $closure) {
  985.                     $value = $closure($this, $value);
  986.                 }
  987.             } finally {
  988.                 unset($this->calling[$option]);
  989.             }
  990.             // END
  991.         }
  993.         // Validate the type of the resolved option
  994.         if (isset($this->allowedTypes[$option])) {
  995.             $valid = true;
  996.             $invalidTypes = [];
  998.             foreach ($this->allowedTypes[$option] as $type) {
  999.                 $type = self::$typeAliases[$type] ?? $type;
  1001.                 if ($valid = $this->verifyTypes($type, $value, $invalidTypes)) {
  1002.                     break;
  1003.                 }
  1004.             }
  1006.             if (!$valid) {
  1007.                 $fmtActualValue = $this->formatValue($value);
  1008.                 $fmtAllowedTypes = implode('" or "', $this->allowedTypes[$option]);
  1009.                 $fmtProvidedTypes = implode('|', array_keys($invalidTypes));
  1010.                 $allowedContainsArrayType = \count(array_filter($this->allowedTypes[$option], static function ($item) {
  1011.                     return '[]' === substr(self::$typeAliases[$item] ?? $item, -2);
  1012.                 })) > 0;
  1014.                 if (\is_array($value) && $allowedContainsArrayType) {
  1015.                     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));
  1016.                 }
  1018.                 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));
  1019.             }
  1020.         }
  1022.         // Validate the value of the resolved option
  1023.         if (isset($this->allowedValues[$option])) {
  1024.             $success = false;
  1025.             $printableAllowedValues = [];
  1027.             foreach ($this->allowedValues[$option] as $allowedValue) {
  1028.                 if ($allowedValue instanceof \Closure) {
  1029.                     if ($allowedValue($value)) {
  1030.                         $success = true;
  1031.                         break;
  1032.                     }
  1034.                     // Don't include closures in the exception message
  1035.                     continue;
  1036.                 }
  1038.                 if ($value === $allowedValue) {
  1039.                     $success = true;
  1040.                     break;
  1041.                 }
  1043.                 $printableAllowedValues[] = $allowedValue;
  1044.             }
  1046.             if (!$success) {
  1047.                 $message = sprintf(
  1048.                     'The option "%s" with value %s is invalid.',
  1049.                     $option,
  1050.                     $this->formatValue($value)
  1051.                 );
  1053.                 if (\count($printableAllowedValues) > 0) {
  1054.                     $message .= sprintf(
  1055.                         ' Accepted values are: %s.',
  1056.                         $this->formatValues($printableAllowedValues)
  1057.                     );
  1058.                 }
  1060.                 if (isset($this->info[$option])) {
  1061.                     $message .= sprintf(' Info: %s.', $this->info[$option]);
  1062.                 }
  1064.                 throw new InvalidOptionsException($message);
  1065.             }
  1066.         }
  1068.         // Check whether the option is deprecated
  1069.         // and it is provided by the user or is being called from a lazy evaluation
  1070.         if ($triggerDeprecation && isset($this->deprecated[$option]) && (isset($this->given[$option]) || ($this->calling && \is_string($this->deprecated[$option]['message'])))) {
  1071.             $deprecation = $this->deprecated[$option];
  1072.             $message = $this->deprecated[$option]['message'];
  1074.             if ($message instanceof \Closure) {
  1075.                 // If the closure is already being called, we have a cyclic dependency
  1076.                 if (isset($this->calling[$option])) {
  1077.                     throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  1078.                 }
  1080.                 $this->calling[$option] = true;
  1081.                 try {
  1082.                     if (!\is_string($message = $message($this, $value))) {
  1083.                         throw new InvalidOptionsException(sprintf('Invalid type for deprecation message, expected string but got "%s", return an empty string to ignore.', get_debug_type($message)));
  1084.                     }
  1085.                 } finally {
  1086.                     unset($this->calling[$option]);
  1087.                 }
  1088.             }
  1090.             if ('' !== $message) {
  1091.                 trigger_deprecation($deprecation['package'], $deprecation['version'], strtr($message, ['%name%' => $option]));
  1092.             }
  1093.         }
  1095.         // Normalize the validated option
  1096.         if (isset($this->normalizers[$option])) {
  1097.             // If the closure is already being called, we have a cyclic
  1098.             // dependency
  1099.             if (isset($this->calling[$option])) {
  1100.                 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', $this->formatOptions(array_keys($this->calling))));
  1101.             }
  1103.             // The following section must be protected from cyclic
  1104.             // calls. Set $calling for the current $option to detect a cyclic
  1105.             // dependency
  1106.             // BEGIN
  1107.             $this->calling[$option] = true;
  1108.             try {
  1109.                 foreach ($this->normalizers[$option] as $normalizer) {
  1110.                     $value = $normalizer($this, $value);
  1111.                 }
  1112.             } finally {
  1113.                 unset($this->calling[$option]);
  1114.             }
  1115.             // END
  1116.         }
  1118.         // Mark as resolved
  1119.         $this->resolved[$option] = $value;
  1121.         return $value;
  1122.     }
  1124.     private function verifyTypes(string $type, $value, array &$invalidTypes, int $level = 0): bool
  1125.     {
  1126.         if (\is_array($value) && '[]' === substr($type, -2)) {
  1127.             $type = substr($type, 0, -2);
  1128.             $valid = true;
  1130.             foreach ($value as $val) {
  1131.                 if (!$this->verifyTypes($type, $val, $invalidTypes, $level + 1)) {
  1132.                     $valid = false;
  1133.                 }
  1134.             }
  1136.             return $valid;
  1137.         }
  1139.         if (('null' === $type && null === $value) || (\function_exists($func = 'is_'.$type) && $func($value)) || $value instanceof $type) {
  1140.             return true;
  1141.         }
  1143.         if (!$invalidTypes || $level > 0) {
  1144.             $invalidTypes[get_debug_type($value)] = true;
  1145.         }
  1147.         return false;
  1148.     }
  1150.     /**
  1151.      * Returns whether a resolved option with the given name exists.
  1152.      *
  1153.      * @param string $option The option name
  1154.      *
  1155.      * @return bool Whether the option is set
  1156.      *
  1157.      * @throws AccessException If accessing this method outside of {@link resolve()}
  1158.      *
  1159.      * @see \ArrayAccess::offsetExists()
  1160.      */
  1161.     public function offsetExists($option)
  1162.     {
  1163.         if (!$this->locked) {
  1164.             throw new AccessException('Array access is only supported within closures of lazy options and normalizers.');
  1165.         }
  1167.         return \array_key_exists($option, $this->defaults);
  1168.     }
  1170.     /**
  1171.      * Not supported.
  1172.      *
  1173.      * @throws AccessException
  1174.      */
  1175.     public function offsetSet($option, $value)
  1176.     {
  1177.         throw new AccessException('Setting options via array access is not supported. Use setDefault() instead.');
  1178.     }
  1180.     /**
  1181.      * Not supported.
  1182.      *
  1183.      * @throws AccessException
  1184.      */
  1185.     public function offsetUnset($option)
  1186.     {
  1187.         throw new AccessException('Removing options via array access is not supported. Use remove() instead.');
  1188.     }
  1190.     /**
  1191.      * Returns the number of set options.
  1192.      *
  1193.      * This may be only a subset of the defined options.
  1194.      *
  1195.      * @return int Number of options
  1196.      *
  1197.      * @throws AccessException If accessing this method outside of {@link resolve()}
  1198.      *
  1199.      * @see \Countable::count()
  1200.      */
  1201.     public function count()
  1202.     {
  1203.         if (!$this->locked) {
  1204.             throw new AccessException('Counting is only supported within closures of lazy options and normalizers.');
  1205.         }
  1207.         return \count($this->defaults);
  1208.     }
  1210.     /**
  1211.      * Returns a string representation of the value.
  1212.      *
  1213.      * This method returns the equivalent PHP tokens for most scalar types
  1214.      * (i.e. "false" for false, "1" for 1 etc.). Strings are always wrapped
  1215.      * in double quotes (").
  1216.      *
  1217.      * @param mixed $value The value to format as string
  1218.      */
  1219.     private function formatValue($value): string
  1220.     {
  1221.         if (\is_object($value)) {
  1222.             return \get_class($value);
  1223.         }
  1225.         if (\is_array($value)) {
  1226.             return 'array';
  1227.         }
  1229.         if (\is_string($value)) {
  1230.             return '"'.$value.'"';
  1231.         }
  1233.         if (\is_resource($value)) {
  1234.             return 'resource';
  1235.         }
  1237.         if (null === $value) {
  1238.             return 'null';
  1239.         }
  1241.         if (false === $value) {
  1242.             return 'false';
  1243.         }
  1245.         if (true === $value) {
  1246.             return 'true';
  1247.         }
  1249.         return (string) $value;
  1250.     }
  1252.     /**
  1253.      * Returns a string representation of a list of values.
  1254.      *
  1255.      * Each of the values is converted to a string using
  1256.      * {@link formatValue()}. The values are then concatenated with commas.
  1257.      *
  1258.      * @see formatValue()
  1259.      */
  1260.     private function formatValues(array $values): string
  1261.     {
  1262.         foreach ($values as $key => $value) {
  1263.             $values[$key] = $this->formatValue($value);
  1264.         }
  1266.         return implode(', ', $values);
  1267.     }
  1269.     private function formatOptions(array $options): string
  1270.     {
  1271.         if ($this->parentsOptions) {
  1272.             $prefix = array_shift($this->parentsOptions);
  1273.             if ($this->parentsOptions) {
  1274.                 $prefix .= sprintf('[%s]', implode('][', $this->parentsOptions));
  1275.             }
  1277.             $options = array_map(static function (string $option) use ($prefix): string {
  1278.                 return sprintf('%s[%s]', $prefix, $option);
  1279.             }, $options);
  1280.         }
  1282.         return implode('", "', $options);
  1283.     }
  1285.     private function getParameterClassName(\ReflectionParameter $parameter): ?string
  1286.     {
  1287.         if (!($type = $parameter->getType()) instanceof \ReflectionNamedType || $type->isBuiltin()) {
  1288.             return null;
  1289.         }
  1291.         return $type->getName();
  1292.     }
  1293. }