NodeDefinition.php 8.7 KB

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