Skip to content

Commit bc0d884

Browse files
smnandresmnandre
committed
[Console] Document the TreeHelper
PR #59588 fix symfony#20692
1 parent d688f63 commit bc0d884

File tree

3 files changed

+257
-0
lines changed

3 files changed

+257
-0
lines changed

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

Lines changed: 1 addition & 0 deletions
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

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

‎console/style.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,27 @@ 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+
:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::createTree`
189+
Creates an instance of :class:`Symfony\\Component\\Console\\Helper\\TreeHelper`
190+
styled according to the Symfony Style Guide, which allows you to use
191+
features such as dynamically nesting nodes.
192+
172193
:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::newLine`
173194
It displays a blank line in the command output. Although it may seem useful,
174195
most of the times you won't need it at all. The reason is that every helper

0 commit comments

Comments
 (0)