4 * This file is part of the Symfony package.
6 * (c) Fabien Potencier <fabien@symfony.com>
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
12 namespace Symfony\Component\Config\Definition;
14 use Symfony\Component\Config\Definition\Exception\DuplicateKeyException;
15 use Symfony\Component\Config\Definition\Exception\Exception;
16 use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
17 use Symfony\Component\Config\Definition\Exception\UnsetKeyException;
20 * Represents a prototyped Array node in the config tree.
22 * @author Johannes M. Schmitt <schmittjoh@gmail.com>
24 class PrototypedArrayNode extends ArrayNode
27 protected $keyAttribute;
28 protected $removeKeyAttribute = false;
29 protected $minNumberOfElements = 0;
30 protected $defaultValue = array();
31 protected $defaultChildren;
33 * @var NodeInterface[] An array of the prototypes of the simplified value children
35 private $valuePrototypes = array();
38 * Sets the minimum number of elements that a prototype based node must
39 * contain. By default this is zero, meaning no elements.
43 public function setMinNumberOfElements($number)
45 $this->minNumberOfElements = $number;
49 * Sets the attribute which value is to be used as key.
51 * This is useful when you have an indexed array that should be an
52 * associative array. You can select an item from within the array
53 * to be the key of the particular item. For example, if "id" is the
57 * array('id' => 'my_name', 'foo' => 'bar'),
63 * 'my_name' => array('foo' => 'bar'),
66 * If you'd like "'id' => 'my_name'" to still be present in the resulting
67 * array, then you can set the second argument of this method to false.
69 * @param string $attribute The name of the attribute which value is to be used as a key
70 * @param bool $remove Whether or not to remove the key
72 public function setKeyAttribute($attribute, $remove = true)
74 $this->keyAttribute = $attribute;
75 $this->removeKeyAttribute = $remove;
79 * Retrieves the name of the attribute which value should be used as key.
81 * @return string The name of the attribute
83 public function getKeyAttribute()
85 return $this->keyAttribute;
89 * Sets the default value of this node.
91 * @param string $value
93 * @throws \InvalidArgumentException if the default value is not an array
95 public function setDefaultValue($value)
97 if (!\is_array($value)) {
98 throw new \InvalidArgumentException($this->getPath().': the default value of an array node has to be an array.');
101 $this->defaultValue = $value;
107 public function hasDefaultValue()
113 * Adds default children when none are set.
115 * @param int|string|array|null $children The number of children|The child name|The children names to be added
117 public function setAddChildrenIfNoneSet($children = array('defaults'))
119 if (null === $children) {
120 $this->defaultChildren = array('defaults');
122 $this->defaultChildren = \is_int($children) && $children > 0 ? range(1, $children) : (array) $children;
129 * The default value could be either explicited or derived from the prototype
132 public function getDefaultValue()
134 if (null !== $this->defaultChildren) {
135 $default = $this->prototype->hasDefaultValue() ? $this->prototype->getDefaultValue() : array();
137 foreach (array_values($this->defaultChildren) as $i => $name) {
138 $defaults[null === $this->keyAttribute ? $i : $name] = $default;
144 return $this->defaultValue;
148 * Sets the node prototype.
150 public function setPrototype(PrototypeNodeInterface $node)
152 $this->prototype = $node;
156 * Retrieves the prototype.
158 * @return PrototypeNodeInterface The prototype
160 public function getPrototype()
162 return $this->prototype;
166 * Disable adding concrete children for prototyped nodes.
170 public function addChild(NodeInterface $node)
172 throw new Exception('A prototyped array node can not have concrete children.');
176 * Finalizes the value of this node.
178 * @param mixed $value
180 * @return mixed The finalized value
182 * @throws UnsetKeyException
183 * @throws InvalidConfigurationException if the node doesn't have enough children
185 protected function finalizeValue($value)
187 if (false === $value) {
188 throw new UnsetKeyException(sprintf('Unsetting key for path "%s", value: %s', $this->getPath(), json_encode($value)));
191 foreach ($value as $k => $v) {
192 $prototype = $this->getPrototypeForChild($k);
194 $value[$k] = $prototype->finalize($v);
195 } catch (UnsetKeyException $e) {
200 if (\count($value) < $this->minNumberOfElements) {
201 $ex = new InvalidConfigurationException(sprintf('The path "%s" should have at least %d element(s) defined.', $this->getPath(), $this->minNumberOfElements));
202 $ex->setPath($this->getPath());
211 * Normalizes the value.
213 * @param mixed $value The value to normalize
215 * @return mixed The normalized value
217 * @throws InvalidConfigurationException
218 * @throws DuplicateKeyException
220 protected function normalizeValue($value)
222 if (false === $value) {
226 $value = $this->remapXml($value);
228 $isAssoc = array_keys($value) !== range(0, \count($value) - 1);
229 $normalized = array();
230 foreach ($value as $k => $v) {
231 if (null !== $this->keyAttribute && \is_array($v)) {
232 if (!isset($v[$this->keyAttribute]) && \is_int($k) && !$isAssoc) {
233 $ex = new InvalidConfigurationException(sprintf('The attribute "%s" must be set for path "%s".', $this->keyAttribute, $this->getPath()));
234 $ex->setPath($this->getPath());
237 } elseif (isset($v[$this->keyAttribute])) {
238 $k = $v[$this->keyAttribute];
240 // remove the key attribute when required
241 if ($this->removeKeyAttribute) {
242 unset($v[$this->keyAttribute]);
245 // if only "value" is left
246 if (array_keys($v) === array('value')) {
248 if ($this->prototype instanceof ArrayNode && ($children = $this->prototype->getChildren()) && array_key_exists('value', $children)) {
249 $valuePrototype = current($this->valuePrototypes) ?: clone $children['value'];
250 $valuePrototype->parent = $this;
251 $originalClosures = $this->prototype->normalizationClosures;
252 if (\is_array($originalClosures)) {
253 $valuePrototypeClosures = $valuePrototype->normalizationClosures;
254 $valuePrototype->normalizationClosures = \is_array($valuePrototypeClosures) ? array_merge($originalClosures, $valuePrototypeClosures) : $originalClosures;
256 $this->valuePrototypes[$k] = $valuePrototype;
261 if (array_key_exists($k, $normalized)) {
262 $ex = new DuplicateKeyException(sprintf('Duplicate key "%s" for path "%s".', $k, $this->getPath()));
263 $ex->setPath($this->getPath());
269 $prototype = $this->getPrototypeForChild($k);
270 if (null !== $this->keyAttribute || $isAssoc) {
271 $normalized[$k] = $prototype->normalize($v);
273 $normalized[] = $prototype->normalize($v);
281 * Merges values together.
283 * @param mixed $leftSide The left side to merge
284 * @param mixed $rightSide The right side to merge
286 * @return mixed The merged values
288 * @throws InvalidConfigurationException
289 * @throws \RuntimeException
291 protected function mergeValues($leftSide, $rightSide)
293 if (false === $rightSide) {
294 // if this is still false after the last config has been merged the
295 // finalization pass will take care of removing this key entirely
299 if (false === $leftSide || !$this->performDeepMerging) {
303 foreach ($rightSide as $k => $v) {
304 // prototype, and key is irrelevant, so simply append the element
305 if (null === $this->keyAttribute) {
311 if (!array_key_exists($k, $leftSide)) {
312 if (!$this->allowNewKeys) {
313 $ex = new InvalidConfigurationException(sprintf('You are not allowed to define new elements for path "%s". Please define all elements for this path in one config file.', $this->getPath()));
314 $ex->setPath($this->getPath());
323 $prototype = $this->getPrototypeForChild($k);
324 $leftSide[$k] = $prototype->merge($leftSide[$k], $v);
331 * Returns a prototype for the child node that is associated to $key in the value array.
332 * For general child nodes, this will be $this->prototype.
333 * But if $this->removeKeyAttribute is true and there are only two keys in the child node:
334 * one is same as this->keyAttribute and the other is 'value', then the prototype will be different.
336 * For example, assume $this->keyAttribute is 'name' and the value array is as follows:
340 * 'name' => 'name001',
341 * 'value' => 'value001'
345 * Now, the key is 0 and the child node is:
348 * 'name' => 'name001',
349 * 'value' => 'value001'
352 * When normalizing the value array, the 'name' element will removed from the child node
353 * and its value becomes the new key of the child node:
356 * 'name001' => array('value' => 'value001')
359 * Now only 'value' element is left in the child node which can be further simplified into a string:
361 * array('name001' => 'value001')
363 * Now, the key becomes 'name001' and the child node becomes 'value001' and
364 * the prototype of child node 'name001' should be a ScalarNode instead of an ArrayNode instance.
366 * @param string $key The key of the child node
368 * @return mixed The prototype instance
370 private function getPrototypeForChild($key)
372 $prototype = isset($this->valuePrototypes[$key]) ? $this->valuePrototypes[$key] : $this->prototype;
373 $prototype->setName($key);