Skip to content

Commit b39f1c1

Browse files
javiereguiluzjaviereguiluz
committed
minor #20786 [Console] Document the TreeHelper (smnandre)
This PR was squashed before being merged into the 7.3 branch. Discussion ---------- [Console] Document the `TreeHelper` | Q | A | | - | - | | Feature PR | [symfony/symfony#59588](symfony/symfony#59588) | | PR author(s) | [`@smnandre`](https://github.com/smnandre) | | Merged in | 7.3 | | Doc Issue | Fix #20692 | fix #20692 Commits ------- d9a48be [Console] Document the `TreeHelper`
2 parents e2983cc + d9a48be commit b39f1c1

File tree

3 files changed

+264
-0
lines changed

3 files changed

+264
-0
lines changed

‎components/console/helpers/map.rst.inc

+1
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
* :doc:`/components/console/helpers/progressbar`
44
* :doc:`/components/console/helpers/questionhelper`
55
* :doc:`/components/console/helpers/table`
6+
* :doc:`/components/console/helpers/tree`
67
* :doc:`/components/console/helpers/debug_formatter`
78
* :doc:`/components/console/helpers/cursor`

‎components/console/helpers/tree.rst

+237
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
Tree Helper
2+
===========
3+
4+
The Tree Helper allows you to build and display tree structures in the console.
5+
6+
.. versionadded:: 7.3
7+
8+
The ``TreeHelper`` class was introduced in Symfony 7.3.
9+
10+
Rendering a Tree
11+
----------------
12+
13+
The :method:`Symfony\\Component\\Console\\Helper\\TreeHelper::createTree` method creates a tree structure from an array and returns a :class:`Symfony\\Component\\Console\\Helper\\Tree`
14+
object that can be rendered in the console.
15+
16+
Building a Tree from an Array
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
19+
You can build a tree from an array by passing the array to the :method:`Symfony\\Component\\Console\\Helper\\TreeHelper::createTree`
20+
method::
21+
22+
use Symfony\Component\Console\Helper\TreeHelper;
23+
24+
$tree = TreeHelper::createTree($io, null, [
25+
'src' => [
26+
'Command',
27+
'Controller' => [
28+
'DefaultController.php',
29+
],
30+
'Kernel.php',
31+
],
32+
'templates' => [
33+
'base.html.twig',
34+
],
35+
]);
36+
37+
$tree->render();
38+
39+
The above code will output the following tree:
40+
41+
.. code-block:: text
42+
43+
├── src
44+
│ ├── Command
45+
│ ├── Controller
46+
│ │ └── DefaultController.php
47+
│ └── Kernel.php
48+
└── templates
49+
└── base.html.twig
50+
51+
Manually Creating a Tree
52+
~~~~~~~~~~~~~~~~~~~~~~~~
53+
54+
You can manually create a tree by creating a new instance of the :class:`Symfony\\Component\\Console\\Helper\\Tree` class and adding nodes to it::
55+
56+
use Symfony\Component\Console\Helper\TreeHelper;
57+
use Symfony\Component\Console\Helper\TreeNode;
58+
59+
$node = TreeNode::fromValues([
60+
'Command',
61+
'Controller' => [
62+
'DefaultController.php',
63+
],
64+
'Kernel.php',
65+
]);
66+
$node->addChild('templates');
67+
$node->addChild('tests');
68+
69+
$tree = TreeHelper::createTree($io, $node);
70+
$tree->render();
71+
72+
Customizing the Tree Style
73+
--------------------------
74+
75+
Built-in Tree Styles
76+
~~~~~~~~~~~~~~~~~~~~
77+
78+
The tree helper provides a few built-in styles that you can use to customize the output of the tree.
79+
80+
:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::default`
81+
82+
.. code-block:: text
83+
84+
├── config
85+
│ ├── packages
86+
│ └── routes
87+
│ ├── framework.yaml
88+
│ └── web_profiler.yaml
89+
├── src
90+
│ ├── Command
91+
│ ├── Controller
92+
│ │ └── DefaultController.php
93+
│ └── Kernel.php
94+
└── templates
95+
└── base.html.twig
96+
97+
:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::box`
98+
99+
.. code-block:: text
100+
101+
┃╸ config
102+
┃ ┃╸ packages
103+
┃ ┗╸ routes
104+
┃ ┃╸ framework.yaml
105+
┃ ┗╸ web_profiler.yaml
106+
┃╸ src
107+
┃ ┃╸ Command
108+
┃ ┃╸ Controller
109+
┃ ┃ ┗╸ DefaultController.php
110+
┃ ┗╸ Kernel.php
111+
┗╸ templates
112+
┗╸ base.html.twig
113+
114+
:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::doubleBox`
115+
116+
.. code-block:: text
117+
118+
╠═ config
119+
║ ╠═ packages
120+
║ ╚═ routes
121+
║ ╠═ framework.yaml
122+
║ ╚═ web_profiler.yaml
123+
╠═ src
124+
║ ╠═ Command
125+
║ ╠═ Controller
126+
║ ║ ╚═ DefaultController.php
127+
║ ╚═ Kernel.php
128+
╚═ templates
129+
╚═ base.html.twig
130+
131+
:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::compact`
132+
133+
.. code-block:: text
134+
135+
├ config
136+
│ ├ packages
137+
│ └ routes
138+
│ ├ framework.yaml
139+
│ └ web_profiler.yaml
140+
├ src
141+
│ ├ Command
142+
│ ├ Controller
143+
│ │ └ DefaultController.php
144+
│ └ Kernel.php
145+
└ templates
146+
└ base.html.twig
147+
148+
:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::light`
149+
150+
.. code-block:: text
151+
152+
|-- config
153+
| |-- packages
154+
| `-- routes
155+
| |-- framework.yaml
156+
| `-- web_profiler.yaml
157+
|-- src
158+
| |-- Command
159+
| |-- Controller
160+
| | `-- DefaultController.php
161+
| `-- Kernel.php
162+
`-- templates
163+
`-- base.html.twig
164+
165+
:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::minimal`
166+
167+
.. code-block:: text
168+
169+
. config
170+
. . packages
171+
. . routes
172+
. . framework.yaml
173+
. . web_profiler.yaml
174+
. src
175+
. . Command
176+
. . Controller
177+
. . . DefaultController.php
178+
. . Kernel.php
179+
. templates
180+
. base.html.twig
181+
182+
:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::rounded`
183+
184+
.. code-block:: text
185+
186+
├─ config
187+
│ ├─ packages
188+
│ ╰─ routes
189+
│ ├─ framework.yaml
190+
│ ╰─ web_profiler.yaml
191+
├─ src
192+
│ ├─ Command
193+
│ ├─ Controller
194+
│ │ ╰─ DefaultController.php
195+
│ ╰─ Kernel.php
196+
╰─ templates
197+
╰─ base.html.twig
198+
199+
Making a Custom Tree Style
200+
~~~~~~~~~~~~~~~~~~~~~~~~~~
201+
202+
You can create your own tree style by passing the characters to the constructor
203+
of the :class:`Symfony\\Component\\Console\\Helper\\TreeStyle` class::
204+
205+
use Symfony\Component\Console\Helper\TreeHelper;
206+
use Symfony\Component\Console\Helper\TreeStyle;
207+
208+
$customStyle = new TreeStyle('🟣 ', '🟠 ', '🔵 ', '🟢 ', '🔴 ', '🟡 ');
209+
210+
// Pass the custom style to the createTree method
211+
212+
$tree = TreeHelper::createTree($io, null, [
213+
'src' => [
214+
'Command',
215+
'Controller' => [
216+
'DefaultController.php',
217+
],
218+
'Kernel.php',
219+
],
220+
'templates' => [
221+
'base.html.twig',
222+
],
223+
], $customStyle);
224+
225+
$tree->render();
226+
227+
The above code will output the following tree:
228+
229+
.. code-block:: text
230+
231+
🔵 🟣 🟡 src
232+
🔵 🟢 🟣 🟡 Command
233+
🔵 🟢 🟣 🟡 Controller
234+
🔵 🟢 🟢 🟠 🟡 DefaultController.php
235+
🔵 🟢 🟠 🟡 Kernel.php
236+
🔵 🟠 🟡 templates
237+
🔵 🔴 🟠 🟡 base.html.twig

‎console/style.rst

+26
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,32 @@ Content Methods
169169
styled according to the Symfony Style Guide, which allows you to use
170170
features such as dynamically appending rows.
171171

172+
:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::tree`
173+
It displays the given nested array as a formatted directory/file tree
174+
structure in the console output::
175+
176+
$io->tree([
177+
'src' => [
178+
'Controller' => [
179+
'DefaultController.php',
180+
],
181+
'Kernel.php',
182+
],
183+
'templates' => [
184+
'base.html.twig',
185+
],
186+
]);
187+
188+
.. versionadded:: 7.3
189+
190+
The ``SymfonyStyle::tree()`` and the ``SymfonyStyle::createTree()`` methods
191+
were introduced in Symfony 7.3.
192+
193+
:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::createTree`
194+
Creates an instance of :class:`Symfony\\Component\\Console\\Helper\\TreeHelper`
195+
styled according to the Symfony Style Guide, which allows you to use
196+
features such as dynamically nesting nodes.
197+
172198
:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::newLine`
173199
It displays a blank line in the command output. Although it may seem useful,
174200
most of the times you won't need it at all. The reason is that every helper

0 commit comments

Comments
 (0)