[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\Builder;
  13  
  14  use Symfony\Component\Config\Definition\Exception\InvalidDefinitionException;
  15  use Symfony\Component\Config\Definition\NodeInterface;
  16  
  17  /**
  18   * This class provides a fluent interface for defining a node.
  19   *
  20   * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  21   */
  22  abstract class NodeDefinition implements NodeParentInterface
  23  {
  24      protected $name;
  25      protected $normalization;
  26      protected $validation;
  27      protected $defaultValue;
  28      protected $default = false;
  29      protected $required = false;
  30      protected $deprecationMessage = null;
  31      protected $merge;
  32      protected $allowEmptyValue = true;
  33      protected $nullEquivalent;
  34      protected $trueEquivalent = true;
  35      protected $falseEquivalent = false;
  36      protected $parent;
  37      protected $attributes = [];
  38  
  39      /**
  40       * @param string|null              $name   The name of the node
  41       * @param NodeParentInterface|null $parent The parent
  42       */
  43      public function __construct($name, NodeParentInterface $parent = null)
  44      {
  45          $this->parent = $parent;
  46          $this->name = $name;
  47      }
  48  
  49      /**
  50       * Sets the parent node.
  51       *
  52       * @return $this
  53       */
  54      public function setParent(NodeParentInterface $parent)
  55      {
  56          $this->parent = $parent;
  57  
  58          return $this;
  59      }
  60  
  61      /**
  62       * Sets info message.
  63       *
  64       * @param string $info The info text
  65       *
  66       * @return $this
  67       */
  68      public function info($info)
  69      {
  70          return $this->attribute('info', $info);
  71      }
  72  
  73      /**
  74       * Sets example configuration.
  75       *
  76       * @param string|array $example
  77       *
  78       * @return $this
  79       */
  80      public function example($example)
  81      {
  82          return $this->attribute('example', $example);
  83      }
  84  
  85      /**
  86       * Sets an attribute on the node.
  87       *
  88       * @param string $key
  89       * @param mixed  $value
  90       *
  91       * @return $this
  92       */
  93      public function attribute($key, $value)
  94      {
  95          $this->attributes[$key] = $value;
  96  
  97          return $this;
  98      }
  99  
 100      /**
 101       * Returns the parent node.
 102       *
 103       * @return NodeParentInterface|NodeBuilder|NodeDefinition|ArrayNodeDefinition|VariableNodeDefinition|null The builder of the parent node
 104       */
 105      public function end()
 106      {
 107          return $this->parent;
 108      }
 109  
 110      /**
 111       * Creates the node.
 112       *
 113       * @param bool $forceRootNode Whether to force this node as the root node
 114       *
 115       * @return NodeInterface
 116       */
 117      public function getNode($forceRootNode = false)
 118      {
 119          if ($forceRootNode) {
 120              $this->parent = null;
 121          }
 122  
 123          if (null !== $this->normalization) {
 124              $this->normalization->before = ExprBuilder::buildExpressions($this->normalization->before);
 125          }
 126  
 127          if (null !== $this->validation) {
 128              $this->validation->rules = ExprBuilder::buildExpressions($this->validation->rules);
 129          }
 130  
 131          $node = $this->createNode();
 132          $node->setAttributes($this->attributes);
 133  
 134          return $node;
 135      }
 136  
 137      /**
 138       * Sets the default value.
 139       *
 140       * @param mixed $value The default value
 141       *
 142       * @return $this
 143       */
 144      public function defaultValue($value)
 145      {
 146          $this->default = true;
 147          $this->defaultValue = $value;
 148  
 149          return $this;
 150      }
 151  
 152      /**
 153       * Sets the node as required.
 154       *
 155       * @return $this
 156       */
 157      public function isRequired()
 158      {
 159          $this->required = true;
 160  
 161          return $this;
 162      }
 163  
 164      /**
 165       * Sets the node as deprecated.
 166       *
 167       * You can use %node% and %path% placeholders in your message to display,
 168       * respectively, the node name and its complete path.
 169       *
 170       * @param string $message Deprecation message
 171       *
 172       * @return $this
 173       */
 174      public function setDeprecated($message = 'The child node "%node%" at path "%path%" is deprecated.')
 175      {
 176          $this->deprecationMessage = $message;
 177  
 178          return $this;
 179      }
 180  
 181      /**
 182       * Sets the equivalent value used when the node contains null.
 183       *
 184       * @param mixed $value
 185       *
 186       * @return $this
 187       */
 188      public function treatNullLike($value)
 189      {
 190          $this->nullEquivalent = $value;
 191  
 192          return $this;
 193      }
 194  
 195      /**
 196       * Sets the equivalent value used when the node contains true.
 197       *
 198       * @param mixed $value
 199       *
 200       * @return $this
 201       */
 202      public function treatTrueLike($value)
 203      {
 204          $this->trueEquivalent = $value;
 205  
 206          return $this;
 207      }
 208  
 209      /**
 210       * Sets the equivalent value used when the node contains false.
 211       *
 212       * @param mixed $value
 213       *
 214       * @return $this
 215       */
 216      public function treatFalseLike($value)
 217      {
 218          $this->falseEquivalent = $value;
 219  
 220          return $this;
 221      }
 222  
 223      /**
 224       * Sets null as the default value.
 225       *
 226       * @return $this
 227       */
 228      public function defaultNull()
 229      {
 230          return $this->defaultValue(null);
 231      }
 232  
 233      /**
 234       * Sets true as the default value.
 235       *
 236       * @return $this
 237       */
 238      public function defaultTrue()
 239      {
 240          return $this->defaultValue(true);
 241      }
 242  
 243      /**
 244       * Sets false as the default value.
 245       *
 246       * @return $this
 247       */
 248      public function defaultFalse()
 249      {
 250          return $this->defaultValue(false);
 251      }
 252  
 253      /**
 254       * Sets an expression to run before the normalization.
 255       *
 256       * @return ExprBuilder
 257       */
 258      public function beforeNormalization()
 259      {
 260          return $this->normalization()->before();
 261      }
 262  
 263      /**
 264       * Denies the node value being empty.
 265       *
 266       * @return $this
 267       */
 268      public function cannotBeEmpty()
 269      {
 270          $this->allowEmptyValue = false;
 271  
 272          return $this;
 273      }
 274  
 275      /**
 276       * Sets an expression to run for the validation.
 277       *
 278       * The expression receives the value of the node and must return it. It can
 279       * modify it.
 280       * An exception should be thrown when the node is not valid.
 281       *
 282       * @return ExprBuilder
 283       */
 284      public function validate()
 285      {
 286          return $this->validation()->rule();
 287      }
 288  
 289      /**
 290       * Sets whether the node can be overwritten.
 291       *
 292       * @param bool $deny Whether the overwriting is forbidden or not
 293       *
 294       * @return $this
 295       */
 296      public function cannotBeOverwritten($deny = true)
 297      {
 298          $this->merge()->denyOverwrite($deny);
 299  
 300          return $this;
 301      }
 302  
 303      /**
 304       * Gets the builder for validation rules.
 305       *
 306       * @return ValidationBuilder
 307       */
 308      protected function validation()
 309      {
 310          if (null === $this->validation) {
 311              $this->validation = new ValidationBuilder($this);
 312          }
 313  
 314          return $this->validation;
 315      }
 316  
 317      /**
 318       * Gets the builder for merging rules.
 319       *
 320       * @return MergeBuilder
 321       */
 322      protected function merge()
 323      {
 324          if (null === $this->merge) {
 325              $this->merge = new MergeBuilder($this);
 326          }
 327  
 328          return $this->merge;
 329      }
 330  
 331      /**
 332       * Gets the builder for normalization rules.
 333       *
 334       * @return NormalizationBuilder
 335       */
 336      protected function normalization()
 337      {
 338          if (null === $this->normalization) {
 339              $this->normalization = new NormalizationBuilder($this);
 340          }
 341  
 342          return $this->normalization;
 343      }
 344  
 345      /**
 346       * Instantiate and configure the node according to this definition.
 347       *
 348       * @return NodeInterface The node instance
 349       *
 350       * @throws InvalidDefinitionException When the definition is invalid
 351       */
 352      abstract protected function createNode();
 353  }