[Console] Document the TreeHelper

components/console/helpers/map.rst.inc

@@ -3,5 +3,6 @@
 * :doc:`/components/console/helpers/progressbar`
 * :doc:`/components/console/helpers/questionhelper`
 * :doc:`/components/console/helpers/table`
+* :doc:`/components/console/helpers/tree`
 * :doc:`/components/console/helpers/debug_formatter`
 * :doc:`/components/console/helpers/cursor`

components/console/helpers/tree.rst

@@ -0,0 +1,237 @@
+Tree Helper
+===========
+
+The Tree Helper allows you to build and display tree structures in the console.
+
+.. versionadded:: 7.3
+
+    The ``TreeHelper`` class was introduced in Symfony 7.3.
+
+Rendering a Tree
+----------------
+
+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`
+object that can be rendered in the console.
+
+Building a Tree from an Array
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can build a tree from an array by passing the array to the :method:`Symfony\\Component\\Console\\Helper\\TreeHelper::createTree`
+method::
+
+    use Symfony\Component\Console\Helper\TreeHelper;
+
+    $tree = TreeHelper::createTree($io, null, [
+        'src' =>  [
+            'Command',
+            'Controller' => [
+                'DefaultController.php',
+            ],
+            'Kernel.php',
+        ],
+        'templates' => [
+            'base.html.twig',
+        ],
+    ]);
+
+    $tree->render();
+
+The above code will output the following tree:
+
+.. code-block:: text
+
+    ├── src
+    │   ├── Command
+    │   ├── Controller
+    │   │   └── DefaultController.php
+    │   └── Kernel.php
+    └── templates
+        └── base.html.twig
+
+Manually Creating a Tree
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+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::
+
+    use Symfony\Component\Console\Helper\TreeHelper;
+    use Symfony\Component\Console\Helper\TreeNode;
+
+    $node = TreeNode::fromValues([
+        'Command',
+        'Controller' => [
+            'DefaultController.php',
+        ],
+        'Kernel.php',
+    ]);
+    $node->addChild('templates');
+    $node->addChild('tests');
+
+    $tree = TreeHelper::createTree($io, $node);
+    $tree->render();
+
+Customizing the Tree Style
+--------------------------
+
+Built-in Tree Styles
+~~~~~~~~~~~~~~~~~~~~
+
+The tree helper provides a few built-in styles that you can use to customize the output of the tree.
+
+:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::default`
+
+    .. code-block:: text
+
+        ├── config
+        │   ├── packages
+        │   └── routes
+        │      ├── framework.yaml
+        │      └── web_profiler.yaml
+        ├── src
+        │   ├── Command
+        │   ├── Controller
+        │   │   └── DefaultController.php
+        │   └── Kernel.php
+        └── templates
+           └── base.html.twig
+
+:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::box`
+
+    .. code-block:: text
+
+        ┃╸ config
+        ┃  ┃╸ packages
+        ┃  ┗╸ routes
+        ┃     ┃╸ framework.yaml
+        ┃     ┗╸ web_profiler.yaml
+        ┃╸ src
+        ┃  ┃╸ Command
+        ┃  ┃╸ Controller
+        ┃  ┃  ┗╸ DefaultController.php
+        ┃  ┗╸ Kernel.php
+        ┗╸ templates
+           ┗╸ base.html.twig
+
+:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::doubleBox`
+
+    .. code-block:: text
+
+        ╠═ config
+        ║  ╠═ packages
+        ║  ╚═ routes
+        ║    ╠═ framework.yaml
+        ║    ╚═ web_profiler.yaml
+        ╠═ src
+        ║  ╠═ Command
+        ║  ╠═ Controller
+        ║  ║  ╚═ DefaultController.php
+        ║  ╚═ Kernel.php
+        ╚═ templates
+          ╚═ base.html.twig
+
+:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::compact`
+
+    .. code-block:: text
+
+        ├ config
+        │ ├ packages
+        │ └ routes
+        │   ├ framework.yaml
+        │   └ web_profiler.yaml
+        ├ src
+        │ ├ Command
+        │ ├ Controller
+        │ │ └ DefaultController.php
+        │ └ Kernel.php
+        └ templates
+          └ base.html.twig
+
+:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::light`
+
+    .. code-block:: text
+
+        |-- config
+        |   |-- packages
+        |   `-- routes
+        |       |-- framework.yaml
+        |       `-- web_profiler.yaml
+        |-- src
+        |   |-- Command
+        |   |-- Controller
+        |   |   `-- DefaultController.php
+        |   `-- Kernel.php
+        `-- templates
+            `-- base.html.twig
+
+:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::minimal`
+
+    .. code-block:: text
+
+        . config
+        . . packages
+        . . routes
+        .   . framework.yaml
+        .   . web_profiler.yaml
+        . src
+        . . Command
+        . . Controller
+        . . . DefaultController.php
+        . . Kernel.php
+        . templates
+          . base.html.twig
+
+:method:`Symfony\\Component\\Console\\Helper\\TreeStyle::rounded`
+
+    .. code-block:: text
+
+        ├─ config
+        │  ├─ packages
+        │  ╰─ routes
+        │     ├─ framework.yaml
+        │     ╰─ web_profiler.yaml
+        ├─ src
+        │  ├─ Command
+        │  ├─ Controller
+        │  │  ╰─ DefaultController.php
+        │  ╰─ Kernel.php
+        ╰─ templates
+           ╰─ base.html.twig
+
+Making a Custom Tree Style
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can create your own tree style by passing the characters to the constructor
+of the :class:`Symfony\\Component\\Console\\Helper\\TreeStyle` class::
+
+    use Symfony\Component\Console\Helper\TreeHelper;
+    use Symfony\Component\Console\Helper\TreeStyle;
+
+    $customStyle = new TreeStyle('🟣 ', '🟠 ', '🔵 ', '🟢 ', '🔴 ', '🟡 ');
+
+    // Pass the custom style to the createTree method
+
+    $tree = TreeHelper::createTree($io, null, [
+        'src' =>  [
+            'Command',
+            'Controller' => [
+                'DefaultController.php',
+            ],
+            'Kernel.php',
+        ],
+        'templates' => [
+            'base.html.twig',
+        ],
+    ], $customStyle);
+
+    $tree->render();
+
+The above code will output the following tree:
+
+.. code-block:: text
+
+    🔵 🟣 🟡 src
+    🔵 🟢 🟣 🟡 Command
+    🔵 🟢 🟣 🟡 Controller
+    🔵 🟢 🟢 🟠 🟡 DefaultController.php
+    🔵 🟢 🟠 🟡 Kernel.php
+    🔵 🟠 🟡 templates
+    🔵 🔴 🟠 🟡 base.html.twig

console/style.rst

@@ -169,6 +169,32 @@ Content Methods
     styled according to the Symfony Style Guide, which allows you to use
     features such as dynamically appending rows.
 
+:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::tree`
+    It displays the given nested array as a formatted directory/file tree
+    structure in the console output::
+
+        $io->tree([
+            'src' =>  [
+                'Controller' => [
+                    'DefaultController.php',
+                ],
+                'Kernel.php',
+            ],
+            'templates' => [
+                'base.html.twig',
+            ],
+        ]);
+
+.. versionadded:: 7.3
+
+    The ``SymfonyStyle::tree()`` and the ``SymfonyStyle::createTree()`` methods
+    were introduced in Symfony 7.3.
+
+:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::createTree`
+    Creates an instance of :class:`Symfony\\Component\\Console\\Helper\\TreeHelper`
+    styled according to the Symfony Style Guide, which allows you to use
+    features such as dynamically nesting nodes.
+
 :method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::newLine`
     It displays a blank line in the command output. Although it may seem useful,
     most of the times you won't need it at all. The reason is that every helper