[Summary view] [Print] [Text view]

   1  <?php
   2  
   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   */
  11  
  12  namespace Symfony\Component\Config\Definition;
  13  
  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  
  19  /**
  20   * The base node class.
  21   *
  22   * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  23   */
  24  abstract class BaseNode implements NodeInterface
  25  {
  26      protected $name;
  27      protected $parent;
  28      protected $normalizationClosures = [];
  29      protected $finalValidationClosures = [];
  30      protected $allowOverwrite = true;
  31      protected $required = false;
  32      protected $deprecationMessage = null;
  33      protected $equivalentValues = [];
  34      protected $attributes = [];
  35  
  36      /**
  37       * @param string|null        $name   The name of the node
  38       * @param NodeInterface|null $parent The parent of this node
  39       *
  40       * @throws \InvalidArgumentException if the name contains a period
  41       */
  42      public function __construct($name, NodeInterface $parent = null)
  43      {
  44          if (false !== strpos($name = (string) $name, '.')) {
  45              throw new \InvalidArgumentException('The name must not contain ".".');
  46          }
  47  
  48          $this->name = $name;
  49          $this->parent = $parent;
  50      }
  51  
  52      /**
  53       * @param string $key
  54       */
  55      public function setAttribute($key, $value)
  56      {
  57          $this->attributes[$key] = $value;
  58      }
  59  
  60      /**
  61       * @param string $key
  62       *
  63       * @return mixed
  64       */
  65      public function getAttribute($key, $default = null)
  66      {
  67          return isset($this->attributes[$key]) ? $this->attributes[$key] : $default;
  68      }
  69  
  70      /**
  71       * @param string $key
  72       *
  73       * @return bool
  74       */
  75      public function hasAttribute($key)
  76      {
  77          return isset($this->attributes[$key]);
  78      }
  79  
  80      /**
  81       * @return array
  82       */
  83      public function getAttributes()
  84      {
  85          return $this->attributes;
  86      }
  87  
  88      public function setAttributes(array $attributes)
  89      {
  90          $this->attributes = $attributes;
  91      }
  92  
  93      /**
  94       * @param string $key
  95       */
  96      public function removeAttribute($key)
  97      {
  98          unset($this->attributes[$key]);
  99      }
 100  
 101      /**
 102       * Sets an info message.
 103       *
 104       * @param string $info
 105       */
 106      public function setInfo($info)
 107      {
 108          $this->setAttribute('info', $info);
 109      }
 110  
 111      /**
 112       * Returns info message.
 113       *
 114       * @return string|null The info text
 115       */
 116      public function getInfo()
 117      {
 118          return $this->getAttribute('info');
 119      }
 120  
 121      /**
 122       * Sets the example configuration for this node.
 123       *
 124       * @param string|array $example
 125       */
 126      public function setExample($example)
 127      {
 128          $this->setAttribute('example', $example);
 129      }
 130  
 131      /**
 132       * Retrieves the example configuration for this node.
 133       *
 134       * @return string|array|null The example
 135       */
 136      public function getExample()
 137      {
 138          return $this->getAttribute('example');
 139      }
 140  
 141      /**
 142       * Adds an equivalent value.
 143       *
 144       * @param mixed $originalValue
 145       * @param mixed $equivalentValue
 146       */
 147      public function addEquivalentValue($originalValue, $equivalentValue)
 148      {
 149          $this->equivalentValues[] = [$originalValue, $equivalentValue];
 150      }
 151  
 152      /**
 153       * Set this node as required.
 154       *
 155       * @param bool $boolean Required node
 156       */
 157      public function setRequired($boolean)
 158      {
 159          $this->required = (bool) $boolean;
 160      }
 161  
 162      /**
 163       * Sets this node as deprecated.
 164       *
 165       * You can use %node% and %path% placeholders in your message to display,
 166       * respectively, the node name and its complete path.
 167       *
 168       * @param string|null $message Deprecated message
 169       */
 170      public function setDeprecated($message)
 171      {
 172          $this->deprecationMessage = $message;
 173      }
 174  
 175      /**
 176       * Sets if this node can be overridden.
 177       *
 178       * @param bool $allow
 179       */
 180      public function setAllowOverwrite($allow)
 181      {
 182          $this->allowOverwrite = (bool) $allow;
 183      }
 184  
 185      /**
 186       * Sets the closures used for normalization.
 187       *
 188       * @param \Closure[] $closures An array of Closures used for normalization
 189       */
 190      public function setNormalizationClosures(array $closures)
 191      {
 192          $this->normalizationClosures = $closures;
 193      }
 194  
 195      /**
 196       * Sets the closures used for final validation.
 197       *
 198       * @param \Closure[] $closures An array of Closures used for final validation
 199       */
 200      public function setFinalValidationClosures(array $closures)
 201      {
 202          $this->finalValidationClosures = $closures;
 203      }
 204  
 205      /**
 206       * {@inheritdoc}
 207       */
 208      public function isRequired()
 209      {
 210          return $this->required;
 211      }
 212  
 213      /**
 214       * Checks if this node is deprecated.
 215       *
 216       * @return bool
 217       */
 218      public function isDeprecated()
 219      {
 220          return null !== $this->deprecationMessage;
 221      }
 222  
 223      /**
 224       * Returns the deprecated message.
 225       *
 226       * @param string $node the configuration node name
 227       * @param string $path the path of the node
 228       *
 229       * @return string
 230       */
 231      public function getDeprecationMessage($node, $path)
 232      {
 233          return strtr($this->deprecationMessage, ['%node%' => $node, '%path%' => $path]);
 234      }
 235  
 236      /**
 237       * {@inheritdoc}
 238       */
 239      public function getName()
 240      {
 241          return $this->name;
 242      }
 243  
 244      /**
 245       * {@inheritdoc}
 246       */
 247      public function getPath()
 248      {
 249          $path = $this->name;
 250  
 251          if (null !== $this->parent) {
 252              $path = $this->parent->getPath().'.'.$path;
 253          }
 254  
 255          return $path;
 256      }
 257  
 258      /**
 259       * {@inheritdoc}
 260       */
 261      final public function merge($leftSide, $rightSide)
 262      {
 263          if (!$this->allowOverwrite) {
 264              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()));
 265          }
 266  
 267          $this->validateType($leftSide);
 268          $this->validateType($rightSide);
 269  
 270          return $this->mergeValues($leftSide, $rightSide);
 271      }
 272  
 273      /**
 274       * {@inheritdoc}
 275       */
 276      final public function normalize($value)
 277      {
 278          $value = $this->preNormalize($value);
 279  
 280          // run custom normalization closures
 281          foreach ($this->normalizationClosures as $closure) {
 282              $value = $closure($value);
 283          }
 284  
 285          // replace value with their equivalent
 286          foreach ($this->equivalentValues as $data) {
 287              if ($data[0] === $value) {
 288                  $value = $data[1];
 289              }
 290          }
 291  
 292          // validate type
 293          $this->validateType($value);
 294  
 295          // normalize value
 296          return $this->normalizeValue($value);
 297      }
 298  
 299      /**
 300       * Normalizes the value before any other normalization is applied.
 301       *
 302       * @param mixed $value
 303       *
 304       * @return mixed The normalized array value
 305       */
 306      protected function preNormalize($value)
 307      {
 308          return $value;
 309      }
 310  
 311      /**
 312       * Returns parent node for this node.
 313       *
 314       * @return NodeInterface|null
 315       */
 316      public function getParent()
 317      {
 318          return $this->parent;
 319      }
 320  
 321      /**
 322       * {@inheritdoc}
 323       */
 324      final public function finalize($value)
 325      {
 326          $this->validateType($value);
 327  
 328          $value = $this->finalizeValue($value);
 329  
 330          // Perform validation on the final value if a closure has been set.
 331          // The closure is also allowed to return another value.
 332          foreach ($this->finalValidationClosures as $closure) {
 333              try {
 334                  $value = $closure($value);
 335              } catch (Exception $e) {
 336                  throw $e;
 337              } catch (\Exception $e) {
 338                  throw new InvalidConfigurationException(sprintf('Invalid configuration for path "%s": ', $this->getPath()).$e->getMessage(), $e->getCode(), $e);
 339              }
 340          }
 341  
 342          return $value;
 343      }
 344  
 345      /**
 346       * Validates the type of a Node.
 347       *
 348       * @param mixed $value The value to validate
 349       *
 350       * @throws InvalidTypeException when the value is invalid
 351       */
 352      abstract protected function validateType($value);
 353  
 354      /**
 355       * Normalizes the value.
 356       *
 357       * @param mixed $value The value to normalize
 358       *
 359       * @return mixed The normalized value
 360       */
 361      abstract protected function normalizeValue($value);
 362  
 363      /**
 364       * Merges two values together.
 365       *
 366       * @param mixed $leftSide
 367       * @param mixed $rightSide
 368       *
 369       * @return mixed The merged value
 370       */
 371      abstract protected function mergeValues($leftSide, $rightSide);
 372  
 373      /**
 374       * Finalizes a value.
 375       *
 376       * @param mixed $value The value to finalize
 377       *
 378       * @return mixed The finalized value
 379       */
 380      abstract protected function finalizeValue($value);
 381  }