vendor/symfony/config/Definition/BaseNode.php line 394

  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\Config\Definition;
  14. use Symfony\Component\Config\Definition\Exception\Exception;
  15. use Symfony\Component\Config\Definition\Exception\ForbiddenOverwriteException;
  16. use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
  17. use Symfony\Component\Config\Definition\Exception\InvalidTypeException;
  18. use Symfony\Component\Config\Definition\Exception\UnsetKeyException;
  20. /**
  21.  * The base node class.
  22.  *
  23.  * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  24.  */
  25. abstract class BaseNode implements NodeInterface
  26. {
  27.     public const DEFAULT_PATH_SEPARATOR = '.';
  29.     private static array $placeholderUniquePrefixes = [];
  30.     private static array $placeholders = [];
  32.     protected $name;
  33.     protected $parent;
  34.     protected $normalizationClosures = [];
  35.     protected $normalizedTypes = [];
  36.     protected $finalValidationClosures = [];
  37.     protected $allowOverwrite = true;
  38.     protected $required = false;
  39.     protected $deprecation = [];
  40.     protected $equivalentValues = [];
  41.     protected $attributes = [];
  42.     protected $pathSeparator;
  44.     private mixed $handlingPlaceholder = null;
  46.     /**
  47.      * @throws \InvalidArgumentException if the name contains a period
  48.      */
  49.     public function __construct(?string $name, NodeInterface $parent = null, string $pathSeparator = self::DEFAULT_PATH_SEPARATOR)
  50.     {
  51.         if (str_contains($name = (string) $name, $pathSeparator)) {
  52.             throw new \InvalidArgumentException('The name must not contain ".'.$pathSeparator.'".');
  53.         }
  55.         $this->name = $name;
  56.         $this->parent = $parent;
  57.         $this->pathSeparator = $pathSeparator;
  58.     }
  60.     /**
  61.      * Register possible (dummy) values for a dynamic placeholder value.
  62.      *
  63.      * Matching configuration values will be processed with a provided value, one by one. After a provided value is
  64.      * successfully processed the configuration value is returned as is, thus preserving the placeholder.
  65.      *
  66.      * @internal
  67.      */
  68.     public static function setPlaceholder(string $placeholder, array $values): void
  69.     {
  70.         if (!$values) {
  71.             throw new \InvalidArgumentException('At least one value must be provided.');
  72.         }
  74.         self::$placeholders[$placeholder] = $values;
  75.     }
  77.     /**
  78.      * Adds a common prefix for dynamic placeholder values.
  79.      *
  80.      * Matching configuration values will be skipped from being processed and are returned as is, thus preserving the
  81.      * placeholder. An exact match provided by {@see setPlaceholder()} might take precedence.
  82.      *
  83.      * @internal
  84.      */
  85.     public static function setPlaceholderUniquePrefix(string $prefix): void
  86.     {
  87.         self::$placeholderUniquePrefixes[] = $prefix;
  88.     }
  90.     /**
  91.      * Resets all current placeholders available.
  92.      *
  93.      * @internal
  94.      */
  95.     public static function resetPlaceholders(): void
  96.     {
  97.         self::$placeholderUniquePrefixes = [];
  98.         self::$placeholders = [];
  99.     }
  101.     public function setAttribute(string $key, mixed $value)
  102.     {
  103.         $this->attributes[$key] = $value;
  104.     }
  106.     public function getAttribute(string $key, mixed $default = null): mixed
  107.     {
  108.         return $this->attributes[$key] ?? $default;
  109.     }
  111.     public function hasAttribute(string $key): bool
  112.     {
  113.         return isset($this->attributes[$key]);
  114.     }
  116.     public function getAttributes(): array
  117.     {
  118.         return $this->attributes;
  119.     }
  121.     public function setAttributes(array $attributes)
  122.     {
  123.         $this->attributes = $attributes;
  124.     }
  126.     public function removeAttribute(string $key)
  127.     {
  128.         unset($this->attributes[$key]);
  129.     }
  131.     /**
  132.      * Sets an info message.
  133.      */
  134.     public function setInfo(string $info)
  135.     {
  136.         $this->setAttribute('info', $info);
  137.     }
  139.     /**
  140.      * Returns info message.
  141.      */
  142.     public function getInfo(): ?string
  143.     {
  144.         return $this->getAttribute('info');
  145.     }
  147.     /**
  148.      * Sets the example configuration for this node.
  149.      */
  150.     public function setExample(string|array $example)
  151.     {
  152.         $this->setAttribute('example', $example);
  153.     }
  155.     /**
  156.      * Retrieves the example configuration for this node.
  157.      */
  158.     public function getExample(): string|array|null
  159.     {
  160.         return $this->getAttribute('example');
  161.     }
  163.     /**
  164.      * Adds an equivalent value.
  165.      */
  166.     public function addEquivalentValue(mixed $originalValue, mixed $equivalentValue)
  167.     {
  168.         $this->equivalentValues[] = [$originalValue, $equivalentValue];
  169.     }
  171.     /**
  172.      * Set this node as required.
  173.      */
  174.     public function setRequired(bool $boolean)
  175.     {
  176.         $this->required = $boolean;
  177.     }
  179.     /**
  180.      * Sets this node as deprecated.
  181.      *
  182.      * @param string $package The name of the composer package that is triggering the deprecation
  183.      * @param string $version The version of the package that introduced the deprecation
  184.      * @param string $message the deprecation message to use
  185.      *
  186.      * You can use %node% and %path% placeholders in your message to display,
  187.      * respectively, the node name and its complete path
  188.      */
  189.     public function setDeprecated(string $package, string $version, string $message = 'The child node "%node%" at path "%path%" is deprecated.')
  190.     {
  191.         $this->deprecation = [
  192.             'package' => $package,
  193.             'version' => $version,
  194.             'message' => $message,
  195.         ];
  196.     }
  198.     /**
  199.      * Sets if this node can be overridden.
  200.      */
  201.     public function setAllowOverwrite(bool $allow)
  202.     {
  203.         $this->allowOverwrite = $allow;
  204.     }
  206.     /**
  207.      * Sets the closures used for normalization.
  208.      *
  209.      * @param \Closure[] $closures An array of Closures used for normalization
  210.      */
  211.     public function setNormalizationClosures(array $closures)
  212.     {
  213.         $this->normalizationClosures = $closures;
  214.     }
  216.     /**
  217.      * Sets the list of types supported by normalization.
  218.      *
  219.      * see ExprBuilder::TYPE_* constants.
  220.      */
  221.     public function setNormalizedTypes(array $types)
  222.     {
  223.         $this->normalizedTypes = $types;
  224.     }
  226.     /**
  227.      * Gets the list of types supported by normalization.
  228.      *
  229.      * see ExprBuilder::TYPE_* constants.
  230.      */
  231.     public function getNormalizedTypes(): array
  232.     {
  233.         return $this->normalizedTypes;
  234.     }
  236.     /**
  237.      * Sets the closures used for final validation.
  238.      *
  239.      * @param \Closure[] $closures An array of Closures used for final validation
  240.      */
  241.     public function setFinalValidationClosures(array $closures)
  242.     {
  243.         $this->finalValidationClosures = $closures;
  244.     }
  246.     public function isRequired(): bool
  247.     {
  248.         return $this->required;
  249.     }
  251.     /**
  252.      * Checks if this node is deprecated.
  253.      */
  254.     public function isDeprecated(): bool
  255.     {
  256.         return (bool) $this->deprecation;
  257.     }
  259.     /**
  260.      * @param string $node The configuration node name
  261.      * @param string $path The path of the node
  262.      */
  263.     public function getDeprecation(string $node, string $path): array
  264.     {
  265.         return [
  266.             'package' => $this->deprecation['package'],
  267.             'version' => $this->deprecation['version'],
  268.             'message' => strtr($this->deprecation['message'], ['%node%' => $node, '%path%' => $path]),
  269.         ];
  270.     }
  272.     public function getName(): string
  273.     {
  274.         return $this->name;
  275.     }
  277.     public function getPath(): string
  278.     {
  279.         if (null !== $this->parent) {
  280.             return $this->parent->getPath().$this->pathSeparator.$this->name;
  281.         }
  283.         return $this->name;
  284.     }
  286.     final public function merge(mixed $leftSide, mixed $rightSide): mixed
  287.     {
  288.         if (!$this->allowOverwrite) {
  289.             throw new ForbiddenOverwriteException(sprintf('Configuration path "%s" cannot be overwritten. You have to define all options for this path, and any of its sub-paths in one configuration section.', $this->getPath()));
  290.         }
  292.         if ($leftSide !== $leftPlaceholders = self::resolvePlaceholderValue($leftSide)) {
  293.             foreach ($leftPlaceholders as $leftPlaceholder) {
  294.                 $this->handlingPlaceholder = $leftSide;
  295.                 try {
  296.                     $this->merge($leftPlaceholder, $rightSide);
  297.                 } finally {
  298.                     $this->handlingPlaceholder = null;
  299.                 }
  300.             }
  302.             return $rightSide;
  303.         }
  305.         if ($rightSide !== $rightPlaceholders = self::resolvePlaceholderValue($rightSide)) {
  306.             foreach ($rightPlaceholders as $rightPlaceholder) {
  307.                 $this->handlingPlaceholder = $rightSide;
  308.                 try {
  309.                     $this->merge($leftSide, $rightPlaceholder);
  310.                 } finally {
  311.                     $this->handlingPlaceholder = null;
  312.                 }
  313.             }
  315.             return $rightSide;
  316.         }
  318.         $this->doValidateType($leftSide);
  319.         $this->doValidateType($rightSide);
  321.         return $this->mergeValues($leftSide, $rightSide);
  322.     }
  324.     final public function normalize(mixed $value): mixed
  325.     {
  326.         $value = $this->preNormalize($value);
  328.         // run custom normalization closures
  329.         foreach ($this->normalizationClosures as $closure) {
  330.             $value = $closure($value);
  331.         }
  333.         // resolve placeholder value
  334.         if ($value !== $placeholders = self::resolvePlaceholderValue($value)) {
  335.             foreach ($placeholders as $placeholder) {
  336.                 $this->handlingPlaceholder = $value;
  337.                 try {
  338.                     $this->normalize($placeholder);
  339.                 } finally {
  340.                     $this->handlingPlaceholder = null;
  341.                 }
  342.             }
  344.             return $value;
  345.         }
  347.         // replace value with their equivalent
  348.         foreach ($this->equivalentValues as $data) {
  349.             if ($data[0] === $value) {
  350.                 $value = $data[1];
  351.             }
  352.         }
  354.         // validate type
  355.         $this->doValidateType($value);
  357.         // normalize value
  358.         return $this->normalizeValue($value);
  359.     }
  361.     /**
  362.      * Normalizes the value before any other normalization is applied.
  363.      */
  364.     protected function preNormalize(mixed $value): mixed
  365.     {
  366.         return $value;
  367.     }
  369.     /**
  370.      * Returns parent node for this node.
  371.      */
  372.     public function getParent(): ?NodeInterface
  373.     {
  374.         return $this->parent;
  375.     }
  377.     final public function finalize(mixed $value): mixed
  378.     {
  379.         if ($value !== $placeholders = self::resolvePlaceholderValue($value)) {
  380.             foreach ($placeholders as $placeholder) {
  381.                 $this->handlingPlaceholder = $value;
  382.                 try {
  383.                     $this->finalize($placeholder);
  384.                 } finally {
  385.                     $this->handlingPlaceholder = null;
  386.                 }
  387.             }
  389.             return $value;
  390.         }
  392.         $this->doValidateType($value);
  394.         $value = $this->finalizeValue($value);
  396.         // Perform validation on the final value if a closure has been set.
  397.         // The closure is also allowed to return another value.
  398.         foreach ($this->finalValidationClosures as $closure) {
  399.             try {
  400.                 $value = $closure($value);
  401.             } catch (Exception $e) {
  402.                 if ($e instanceof UnsetKeyException && null !== $this->handlingPlaceholder) {
  403.                     continue;
  404.                 }
  406.                 throw $e;
  407.             } catch (\Exception $e) {
  408.                 throw new InvalidConfigurationException(sprintf('Invalid configuration for path "%s": ', $this->getPath()).$e->getMessage(), $e->getCode(), $e);
  409.             }
  410.         }
  412.         return $value;
  413.     }
  415.     /**
  416.      * Validates the type of a Node.
  417.      *
  418.      * @throws InvalidTypeException when the value is invalid
  419.      */
  420.     abstract protected function validateType(mixed $value);
  422.     /**
  423.      * Normalizes the value.
  424.      */
  425.     abstract protected function normalizeValue(mixed $value): mixed;
  427.     /**
  428.      * Merges two values together.
  429.      */
  430.     abstract protected function mergeValues(mixed $leftSide, mixed $rightSide): mixed;
  432.     /**
  433.      * Finalizes a value.
  434.      */
  435.     abstract protected function finalizeValue(mixed $value): mixed;
  437.     /**
  438.      * Tests if placeholder values are allowed for this node.
  439.      */
  440.     protected function allowPlaceholders(): bool
  441.     {
  442.         return true;
  443.     }
  445.     /**
  446.      * Tests if a placeholder is being handled currently.
  447.      */
  448.     protected function isHandlingPlaceholder(): bool
  449.     {
  450.         return null !== $this->handlingPlaceholder;
  451.     }
  453.     /**
  454.      * Gets allowed dynamic types for this node.
  455.      */
  456.     protected function getValidPlaceholderTypes(): array
  457.     {
  458.         return [];
  459.     }
  461.     private static function resolvePlaceholderValue(mixed $value): mixed
  462.     {
  463.         if (\is_string($value)) {
  464.             if (isset(self::$placeholders[$value])) {
  465.                 return self::$placeholders[$value];
  466.             }
  468.             foreach (self::$placeholderUniquePrefixes as $placeholderUniquePrefix) {
  469.                 if (str_starts_with($value, $placeholderUniquePrefix)) {
  470.                     return [];
  471.                 }
  472.             }
  473.         }
  475.         return $value;
  476.     }
  478.     private function doValidateType(mixed $value): void
  479.     {
  480.         if (null !== $this->handlingPlaceholder && !$this->allowPlaceholders()) {
  481.             $e = new InvalidTypeException(sprintf('A dynamic value is not compatible with a "%s" node type at path "%s".', static::class, $this->getPath()));
  482.             $e->setPath($this->getPath());
  484.             throw $e;
  485.         }
  487.         if (null === $this->handlingPlaceholder || null === $value) {
  488.             $this->validateType($value);
  490.             return;
  491.         }
  493.         $knownTypes = array_keys(self::$placeholders[$this->handlingPlaceholder]);
  494.         $validTypes = $this->getValidPlaceholderTypes();
  496.         if ($validTypes && array_diff($knownTypes, $validTypes)) {
  497.             $e = new InvalidTypeException(sprintf(
  498.                 'Invalid type for path "%s". Expected %s, but got %s.',
  499.                 $this->getPath(),
  500.                 1 === \count($validTypes) ? '"'.reset($validTypes).'"' : 'one of "'.implode('", "', $validTypes).'"',
  501.                 1 === \count($knownTypes) ? '"'.reset($knownTypes).'"' : 'one of "'.implode('", "', $knownTypes).'"'
  502.             ));
  503.             if ($hint = $this->getInfo()) {
  504.                 $e->addHint($hint);
  505.             }
  506.             $e->setPath($this->getPath());
  508.             throw $e;
  509.         }
  511.         $this->validateType($value);
  512.     }
  513. }