vendor/symfony/config/Definition/Builder/ArrayNodeDefinition.php line 169

  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\Builder;
  14. use Symfony\Component\Config\Definition\ArrayNode;
  15. use Symfony\Component\Config\Definition\Exception\InvalidDefinitionException;
  16. use Symfony\Component\Config\Definition\NodeInterface;
  17. use Symfony\Component\Config\Definition\PrototypedArrayNode;
  19. /**
  20.  * This class provides a fluent interface for defining an array node.
  21.  *
  22.  * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  23.  */
  24. class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinitionInterface
  25. {
  26.     protected $performDeepMerging = true;
  27.     protected $ignoreExtraKeys = false;
  28.     protected $removeExtraKeys = true;
  29.     protected $children = [];
  30.     protected $prototype;
  31.     protected $atLeastOne = false;
  32.     protected $allowNewKeys = true;
  33.     protected $key;
  34.     protected $removeKeyItem;
  35.     protected $addDefaults = false;
  36.     protected $addDefaultChildren = false;
  37.     protected $nodeBuilder;
  38.     protected $normalizeKeys = true;
  40.     public function __construct(?string $name, NodeParentInterface $parent = null)
  41.     {
  42.         parent::__construct($name, $parent);
  44.         $this->nullEquivalent = [];
  45.         $this->trueEquivalent = [];
  46.     }
  48.     public function setBuilder(NodeBuilder $builder)
  49.     {
  50.         $this->nodeBuilder = $builder;
  51.     }
  53.     public function children(): NodeBuilder
  54.     {
  55.         return $this->getNodeBuilder();
  56.     }
  58.     /**
  59.      * Sets a prototype for child nodes.
  60.      */
  61.     public function prototype(string $type): NodeDefinition
  62.     {
  63.         return $this->prototype = $this->getNodeBuilder()->node(null, $type)->setParent($this);
  64.     }
  66.     public function variablePrototype(): VariableNodeDefinition
  67.     {
  68.         return $this->prototype('variable');
  69.     }
  71.     public function scalarPrototype(): ScalarNodeDefinition
  72.     {
  73.         return $this->prototype('scalar');
  74.     }
  76.     public function booleanPrototype(): BooleanNodeDefinition
  77.     {
  78.         return $this->prototype('boolean');
  79.     }
  81.     public function integerPrototype(): IntegerNodeDefinition
  82.     {
  83.         return $this->prototype('integer');
  84.     }
  86.     public function floatPrototype(): FloatNodeDefinition
  87.     {
  88.         return $this->prototype('float');
  89.     }
  91.     public function arrayPrototype(): self
  92.     {
  93.         return $this->prototype('array');
  94.     }
  96.     public function enumPrototype(): EnumNodeDefinition
  97.     {
  98.         return $this->prototype('enum');
  99.     }
  101.     /**
  102.      * Adds the default value if the node is not set in the configuration.
  103.      *
  104.      * This method is applicable to concrete nodes only (not to prototype nodes).
  105.      * If this function has been called and the node is not set during the finalization
  106.      * phase, it's default value will be derived from its children default values.
  107.      *
  108.      * @return $this
  109.      */
  110.     public function addDefaultsIfNotSet(): static
  111.     {
  112.         $this->addDefaults = true;
  114.         return $this;
  115.     }
  117.     /**
  118.      * Adds children with a default value when none are defined.
  119.      *
  120.      * This method is applicable to prototype nodes only.
  121.      *
  122.      * @param int|string|array|null $children The number of children|The child name|The children names to be added
  123.      *
  124.      * @return $this
  125.      */
  126.     public function addDefaultChildrenIfNoneSet(int|string|array $children = null): static
  127.     {
  128.         $this->addDefaultChildren = $children;
  130.         return $this;
  131.     }
  133.     /**
  134.      * Requires the node to have at least one element.
  135.      *
  136.      * This method is applicable to prototype nodes only.
  137.      *
  138.      * @return $this
  139.      */
  140.     public function requiresAtLeastOneElement(): static
  141.     {
  142.         $this->atLeastOne = true;
  144.         return $this;
  145.     }
  147.     /**
  148.      * Disallows adding news keys in a subsequent configuration.
  149.      *
  150.      * If used all keys have to be defined in the same configuration file.
  151.      *
  152.      * @return $this
  153.      */
  154.     public function disallowNewKeysInSubsequentConfigs(): static
  155.     {
  156.         $this->allowNewKeys = false;
  158.         return $this;
  159.     }
  161.     /**
  162.      * Sets a normalization rule for XML configurations.
  163.      *
  164.      * @param string      $singular The key to remap
  165.      * @param string|null $plural   The plural of the key for irregular plurals
  166.      *
  167.      * @return $this
  168.      */
  169.     public function fixXmlConfig(string $singular, string $plural = null): static
  170.     {
  171.         $this->normalization()->remap($singular, $plural);
  173.         return $this;
  174.     }
  176.     /**
  177.      * Sets the attribute which value is to be used as key.
  178.      *
  179.      * This is useful when you have an indexed array that should be an
  180.      * associative array. You can select an item from within the array
  181.      * to be the key of the particular item. For example, if "id" is the
  182.      * "key", then:
  183.      *
  184.      *     [
  185.      *         ['id' => 'my_name', 'foo' => 'bar'],
  186.      *     ];
  187.      *
  188.      *   becomes
  189.      *
  190.      *     [
  191.      *         'my_name' => ['foo' => 'bar'],
  192.      *     ];
  193.      *
  194.      * If you'd like "'id' => 'my_name'" to still be present in the resulting
  195.      * array, then you can set the second argument of this method to false.
  196.      *
  197.      * This method is applicable to prototype nodes only.
  198.      *
  199.      * @param string $name          The name of the key
  200.      * @param bool   $removeKeyItem Whether or not the key item should be removed
  201.      *
  202.      * @return $this
  203.      */
  204.     public function useAttributeAsKey(string $name, bool $removeKeyItem = true): static
  205.     {
  206.         $this->key = $name;
  207.         $this->removeKeyItem = $removeKeyItem;
  209.         return $this;
  210.     }
  212.     /**
  213.      * Sets whether the node can be unset.
  214.      *
  215.      * @return $this
  216.      */
  217.     public function canBeUnset(bool $allow = true): static
  218.     {
  219.         $this->merge()->allowUnset($allow);
  221.         return $this;
  222.     }
  224.     /**
  225.      * Adds an "enabled" boolean to enable the current section.
  226.      *
  227.      * By default, the section is disabled. If any configuration is specified then
  228.      * the node will be automatically enabled:
  229.      *
  230.      * enableableArrayNode: {enabled: true, ...}   # The config is enabled & default values get overridden
  231.      * enableableArrayNode: ~                      # The config is enabled & use the default values
  232.      * enableableArrayNode: true                   # The config is enabled & use the default values
  233.      * enableableArrayNode: {other: value, ...}    # The config is enabled & default values get overridden
  234.      * enableableArrayNode: {enabled: false, ...}  # The config is disabled
  235.      * enableableArrayNode: false                  # The config is disabled
  236.      *
  237.      * @return $this
  238.      */
  239.     public function canBeEnabled(): static
  240.     {
  241.         $this
  242.             ->addDefaultsIfNotSet()
  243.             ->treatFalseLike(['enabled' => false])
  244.             ->treatTrueLike(['enabled' => true])
  245.             ->treatNullLike(['enabled' => true])
  246.             ->beforeNormalization()
  247.                 ->ifArray()
  248.                 ->then(function (array $v) {
  249.                     $v['enabled'] ??= true;
  251.                     return $v;
  252.                 })
  253.             ->end()
  254.             ->children()
  255.                 ->booleanNode('enabled')
  256.                     ->defaultFalse()
  257.         ;
  259.         return $this;
  260.     }
  262.     /**
  263.      * Adds an "enabled" boolean to enable the current section.
  264.      *
  265.      * By default, the section is enabled.
  266.      *
  267.      * @return $this
  268.      */
  269.     public function canBeDisabled(): static
  270.     {
  271.         $this
  272.             ->addDefaultsIfNotSet()
  273.             ->treatFalseLike(['enabled' => false])
  274.             ->treatTrueLike(['enabled' => true])
  275.             ->treatNullLike(['enabled' => true])
  276.             ->children()
  277.                 ->booleanNode('enabled')
  278.                     ->defaultTrue()
  279.         ;
  281.         return $this;
  282.     }
  284.     /**
  285.      * Disables the deep merging of the node.
  286.      *
  287.      * @return $this
  288.      */
  289.     public function performNoDeepMerging(): static
  290.     {
  291.         $this->performDeepMerging = false;
  293.         return $this;
  294.     }
  296.     /**
  297.      * Allows extra config keys to be specified under an array without
  298.      * throwing an exception.
  299.      *
  300.      * Those config values are ignored and removed from the resulting
  301.      * array. This should be used only in special cases where you want
  302.      * to send an entire configuration array through a special tree that
  303.      * processes only part of the array.
  304.      *
  305.      * @param bool $remove Whether to remove the extra keys
  306.      *
  307.      * @return $this
  308.      */
  309.     public function ignoreExtraKeys(bool $remove = true): static
  310.     {
  311.         $this->ignoreExtraKeys = true;
  312.         $this->removeExtraKeys = $remove;
  314.         return $this;
  315.     }
  317.     /**
  318.      * Sets whether to enable key normalization.
  319.      *
  320.      * @return $this
  321.      */
  322.     public function normalizeKeys(bool $bool): static
  323.     {
  324.         $this->normalizeKeys = $bool;
  326.         return $this;
  327.     }
  329.     public function append(NodeDefinition $node): static
  330.     {
  331.         $this->children[$node->name] = $node->setParent($this);
  333.         return $this;
  334.     }
  336.     /**
  337.      * Returns a node builder to be used to add children and prototype.
  338.      */
  339.     protected function getNodeBuilder(): NodeBuilder
  340.     {
  341.         $this->nodeBuilder ??= new NodeBuilder();
  343.         return $this->nodeBuilder->setParent($this);
  344.     }
  346.     protected function createNode(): NodeInterface
  347.     {
  348.         if (null === $this->prototype) {
  349.             $node = new ArrayNode($this->name, $this->parent, $this->pathSeparator);
  351.             $this->validateConcreteNode($node);
  353.             $node->setAddIfNotSet($this->addDefaults);
  355.             foreach ($this->children as $child) {
  356.                 $child->parent = $node;
  357.                 $node->addChild($child->getNode());
  358.             }
  359.         } else {
  360.             $node = new PrototypedArrayNode($this->name, $this->parent, $this->pathSeparator);
  362.             $this->validatePrototypeNode($node);
  364.             if (null !== $this->key) {
  365.                 $node->setKeyAttribute($this->key, $this->removeKeyItem);
  366.             }
  368.             if (true === $this->atLeastOne || false === $this->allowEmptyValue) {
  369.                 $node->setMinNumberOfElements(1);
  370.             }
  372.             if ($this->default) {
  373.                 if (!\is_array($this->defaultValue)) {
  374.                     throw new \InvalidArgumentException(sprintf('%s: the default value of an array node has to be an array.', $node->getPath()));
  375.                 }
  377.                 $node->setDefaultValue($this->defaultValue);
  378.             }
  380.             if (false !== $this->addDefaultChildren) {
  381.                 $node->setAddChildrenIfNoneSet($this->addDefaultChildren);
  382.                 if ($this->prototype instanceof static && null === $this->prototype->prototype) {
  383.                     $this->prototype->addDefaultsIfNotSet();
  384.                 }
  385.             }
  387.             $this->prototype->parent = $node;
  388.             $node->setPrototype($this->prototype->getNode());
  389.         }
  391.         $node->setAllowNewKeys($this->allowNewKeys);
  392.         $node->addEquivalentValue(null, $this->nullEquivalent);
  393.         $node->addEquivalentValue(true, $this->trueEquivalent);
  394.         $node->addEquivalentValue(false, $this->falseEquivalent);
  395.         $node->setPerformDeepMerging($this->performDeepMerging);
  396.         $node->setRequired($this->required);
  397.         $node->setIgnoreExtraKeys($this->ignoreExtraKeys, $this->removeExtraKeys);
  398.         $node->setNormalizeKeys($this->normalizeKeys);
  400.         if ($this->deprecation) {
  401.             $node->setDeprecated($this->deprecation['package'], $this->deprecation['version'], $this->deprecation['message']);
  402.         }
  404.         if (null !== $this->normalization) {
  405.             $node->setNormalizationClosures($this->normalization->before);
  406.             $node->setNormalizedTypes($this->normalization->declaredTypes);
  407.             $node->setXmlRemappings($this->normalization->remappings);
  408.         }
  410.         if (null !== $this->merge) {
  411.             $node->setAllowOverwrite($this->merge->allowOverwrite);
  412.             $node->setAllowFalse($this->merge->allowFalse);
  413.         }
  415.         if (null !== $this->validation) {
  416.             $node->setFinalValidationClosures($this->validation->rules);
  417.         }
  419.         return $node;
  420.     }
  422.     /**
  423.      * Validate the configuration of a concrete node.
  424.      *
  425.      * @throws InvalidDefinitionException
  426.      */
  427.     protected function validateConcreteNode(ArrayNode $node)
  428.     {
  429.         $path = $node->getPath();
  431.         if (null !== $this->key) {
  432.             throw new InvalidDefinitionException(sprintf('->useAttributeAsKey() is not applicable to concrete nodes at path "%s".', $path));
  433.         }
  435.         if (false === $this->allowEmptyValue) {
  436.             throw new InvalidDefinitionException(sprintf('->cannotBeEmpty() is not applicable to concrete nodes at path "%s".', $path));
  437.         }
  439.         if (true === $this->atLeastOne) {
  440.             throw new InvalidDefinitionException(sprintf('->requiresAtLeastOneElement() is not applicable to concrete nodes at path "%s".', $path));
  441.         }
  443.         if ($this->default) {
  444.             throw new InvalidDefinitionException(sprintf('->defaultValue() is not applicable to concrete nodes at path "%s".', $path));
  445.         }
  447.         if (false !== $this->addDefaultChildren) {
  448.             throw new InvalidDefinitionException(sprintf('->addDefaultChildrenIfNoneSet() is not applicable to concrete nodes at path "%s".', $path));
  449.         }
  450.     }
  452.     /**
  453.      * Validate the configuration of a prototype node.
  454.      *
  455.      * @throws InvalidDefinitionException
  456.      */
  457.     protected function validatePrototypeNode(PrototypedArrayNode $node)
  458.     {
  459.         $path = $node->getPath();
  461.         if ($this->addDefaults) {
  462.             throw new InvalidDefinitionException(sprintf('->addDefaultsIfNotSet() is not applicable to prototype nodes at path "%s".', $path));
  463.         }
  465.         if (false !== $this->addDefaultChildren) {
  466.             if ($this->default) {
  467.                 throw new InvalidDefinitionException(sprintf('A default value and default children might not be used together at path "%s".', $path));
  468.             }
  470.             if (null !== $this->key && (null === $this->addDefaultChildren || \is_int($this->addDefaultChildren) && $this->addDefaultChildren > 0)) {
  471.                 throw new InvalidDefinitionException(sprintf('->addDefaultChildrenIfNoneSet() should set default children names as ->useAttributeAsKey() is used at path "%s".', $path));
  472.             }
  474.             if (null === $this->key && (\is_string($this->addDefaultChildren) || \is_array($this->addDefaultChildren))) {
  475.                 throw new InvalidDefinitionException(sprintf('->addDefaultChildrenIfNoneSet() might not set default children names as ->useAttributeAsKey() is not used at path "%s".', $path));
  476.             }
  477.         }
  478.     }
  480.     /**
  481.      * @return NodeDefinition[]
  482.      */
  483.     public function getChildNodeDefinitions(): array
  484.     {
  485.         return $this->children;
  486.     }
  488.     /**
  489.      * Finds a node defined by the given $nodePath.
  490.      *
  491.      * @param string $nodePath The path of the node to find. e.g "doctrine.orm.mappings"
  492.      */
  493.     public function find(string $nodePath): NodeDefinition
  494.     {
  495.         $firstPathSegment = (false === $pathSeparatorPos = strpos($nodePath, $this->pathSeparator))
  496.             ? $nodePath
  497.             : substr($nodePath, 0, $pathSeparatorPos);
  499.         if (null === $node = ($this->children[$firstPathSegment] ?? null)) {
  500.             throw new \RuntimeException(sprintf('Node with name "%s" does not exist in the current node "%s".', $firstPathSegment, $this->name));
  501.         }
  503.         if (false === $pathSeparatorPos) {
  504.             return $node;
  505.         }
  507.         return $node->find(substr($nodePath, $pathSeparatorPos + \strlen($this->pathSeparator)));
  508.     }
  509. }