YamlReferenceDumper.php 8.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247
  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\Dumper;
  11. use Symfony\Component\Config\Definition\ArrayNode;
  12. use Symfony\Component\Config\Definition\ConfigurationInterface;
  13. use Symfony\Component\Config\Definition\EnumNode;
  14. use Symfony\Component\Config\Definition\NodeInterface;
  15. use Symfony\Component\Config\Definition\PrototypedArrayNode;
  16. use Symfony\Component\Config\Definition\ScalarNode;
  17. use Symfony\Component\Config\Definition\VariableNode;
  18. use Symfony\Component\Yaml\Inline;
  19. /**
  20. * Dumps a Yaml reference configuration for the given configuration/node instance.
  21. *
  22. * @author Kevin Bond <kevinbond@gmail.com>
  23. */
  24. class YamlReferenceDumper
  25. {
  26. private $reference;
  27. public function dump(ConfigurationInterface $configuration)
  28. {
  29. return $this->dumpNode($configuration->getConfigTreeBuilder()->buildTree());
  30. }
  31. public function dumpAtPath(ConfigurationInterface $configuration, string $path)
  32. {
  33. $rootNode = $node = $configuration->getConfigTreeBuilder()->buildTree();
  34. foreach (explode('.', $path) as $step) {
  35. if (!$node instanceof ArrayNode) {
  36. throw new \UnexpectedValueException(sprintf('Unable to find node at path "%s.%s".', $rootNode->getName(), $path));
  37. }
  38. /** @var NodeInterface[] $children */
  39. $children = $node instanceof PrototypedArrayNode ? $this->getPrototypeChildren($node) : $node->getChildren();
  40. foreach ($children as $child) {
  41. if ($child->getName() === $step) {
  42. $node = $child;
  43. continue 2;
  44. }
  45. }
  46. throw new \UnexpectedValueException(sprintf('Unable to find node at path "%s.%s".', $rootNode->getName(), $path));
  47. }
  48. return $this->dumpNode($node);
  49. }
  50. public function dumpNode(NodeInterface $node)
  51. {
  52. $this->reference = '';
  53. $this->writeNode($node);
  54. $ref = $this->reference;
  55. $this->reference = null;
  56. return $ref;
  57. }
  58. private function writeNode(NodeInterface $node, NodeInterface $parentNode = null, int $depth = 0, bool $prototypedArray = false)
  59. {
  60. $comments = [];
  61. $default = '';
  62. $defaultArray = null;
  63. $children = null;
  64. $example = $node->getExample();
  65. // defaults
  66. if ($node instanceof ArrayNode) {
  67. $children = $node->getChildren();
  68. if ($node instanceof PrototypedArrayNode) {
  69. $children = $this->getPrototypeChildren($node);
  70. }
  71. if (!$children) {
  72. if ($node->hasDefaultValue() && \count($defaultArray = $node->getDefaultValue())) {
  73. $default = '';
  74. } elseif (!\is_array($example)) {
  75. $default = '[]';
  76. }
  77. }
  78. } elseif ($node instanceof EnumNode) {
  79. $comments[] = 'One of '.implode('; ', array_map('json_encode', $node->getValues()));
  80. $default = $node->hasDefaultValue() ? Inline::dump($node->getDefaultValue()) : '~';
  81. } elseif (VariableNode::class === \get_class($node) && \is_array($example)) {
  82. // If there is an array example, we are sure we dont need to print a default value
  83. $default = '';
  84. } else {
  85. $default = '~';
  86. if ($node->hasDefaultValue()) {
  87. $default = $node->getDefaultValue();
  88. if (\is_array($default)) {
  89. if (\count($defaultArray = $node->getDefaultValue())) {
  90. $default = '';
  91. } elseif (!\is_array($example)) {
  92. $default = '[]';
  93. }
  94. } else {
  95. $default = Inline::dump($default);
  96. }
  97. }
  98. }
  99. // required?
  100. if ($node->isRequired()) {
  101. $comments[] = 'Required';
  102. }
  103. // deprecated?
  104. if ($node->isDeprecated()) {
  105. $deprecation = $node->getDeprecation($node->getName(), $parentNode ? $parentNode->getPath() : $node->getPath());
  106. $comments[] = sprintf('Deprecated (%s)', ($deprecation['package'] || $deprecation['version'] ? "Since {$deprecation['package']} {$deprecation['version']}: " : '').$deprecation['message']);
  107. }
  108. // example
  109. if ($example && !\is_array($example)) {
  110. $comments[] = 'Example: '.Inline::dump($example);
  111. }
  112. $default = '' != (string) $default ? ' '.$default : '';
  113. $comments = \count($comments) ? '# '.implode(', ', $comments) : '';
  114. $key = $prototypedArray ? '-' : $node->getName().':';
  115. $text = rtrim(sprintf('%-21s%s %s', $key, $default, $comments), ' ');
  116. if ($info = $node->getInfo()) {
  117. $this->writeLine('');
  118. // indenting multi-line info
  119. $info = str_replace("\n", sprintf("\n%".($depth * 4).'s# ', ' '), $info);
  120. $this->writeLine('# '.$info, $depth * 4);
  121. }
  122. $this->writeLine($text, $depth * 4);
  123. // output defaults
  124. if ($defaultArray) {
  125. $this->writeLine('');
  126. $message = \count($defaultArray) > 1 ? 'Defaults' : 'Default';
  127. $this->writeLine('# '.$message.':', $depth * 4 + 4);
  128. $this->writeArray($defaultArray, $depth + 1);
  129. }
  130. if (\is_array($example)) {
  131. $this->writeLine('');
  132. $message = \count($example) > 1 ? 'Examples' : 'Example';
  133. $this->writeLine('# '.$message.':', $depth * 4 + 4);
  134. $this->writeArray(array_map([Inline::class, 'dump'], $example), $depth + 1);
  135. }
  136. if ($children) {
  137. foreach ($children as $childNode) {
  138. $this->writeNode($childNode, $node, $depth + 1, $node instanceof PrototypedArrayNode && !$node->getKeyAttribute());
  139. }
  140. }
  141. }
  142. /**
  143. * Outputs a single config reference line.
  144. */
  145. private function writeLine(string $text, int $indent = 0)
  146. {
  147. $indent = \strlen($text) + $indent;
  148. $format = '%'.$indent.'s';
  149. $this->reference .= sprintf($format, $text)."\n";
  150. }
  151. private function writeArray(array $array, int $depth)
  152. {
  153. $isIndexed = array_values($array) === $array;
  154. foreach ($array as $key => $value) {
  155. if (\is_array($value)) {
  156. $val = '';
  157. } else {
  158. $val = $value;
  159. }
  160. if ($isIndexed) {
  161. $this->writeLine('- '.$val, $depth * 4);
  162. } else {
  163. $this->writeLine(sprintf('%-20s %s', $key.':', $val), $depth * 4);
  164. }
  165. if (\is_array($value)) {
  166. $this->writeArray($value, $depth + 1);
  167. }
  168. }
  169. }
  170. private function getPrototypeChildren(PrototypedArrayNode $node): array
  171. {
  172. $prototype = $node->getPrototype();
  173. $key = $node->getKeyAttribute();
  174. // Do not expand prototype if it isn't an array node nor uses attribute as key
  175. if (!$key && !$prototype instanceof ArrayNode) {
  176. return $node->getChildren();
  177. }
  178. if ($prototype instanceof ArrayNode) {
  179. $keyNode = new ArrayNode($key, $node);
  180. $children = $prototype->getChildren();
  181. if ($prototype instanceof PrototypedArrayNode && $prototype->getKeyAttribute()) {
  182. $children = $this->getPrototypeChildren($prototype);
  183. }
  184. // add children
  185. foreach ($children as $childNode) {
  186. $keyNode->addChild($childNode);
  187. }
  188. } else {
  189. $keyNode = new ScalarNode($key, $node);
  190. }
  191. $info = 'Prototype';
  192. if (null !== $prototype->getInfo()) {
  193. $info .= ': '.$prototype->getInfo();
  194. }
  195. $keyNode->setInfo($info);
  196. return [$key => $keyNode];
  197. }
  198. }