From d9a48bea00bb340b407402a3f6ada1a265e5eba4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Andr=C3=A9?= Date: Fri, 21 Mar 2025 03:23:02 +0100 Subject: [PATCH] [Console] Document the `TreeHelper` --- components/console/helpers/map.rst.inc | 1 + components/console/helpers/tree.rst | 237 +++++++++++++++++++++++++ console/style.rst | 26 +++ 3 files changed, 264 insertions(+) create mode 100644 components/console/helpers/tree.rst diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc index 8f9ce0ca0f3..b190d1dce44 100644 --- a/components/console/helpers/map.rst.inc +++ b/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` diff --git a/components/console/helpers/tree.rst b/components/console/helpers/tree.rst new file mode 100644 index 00000000000..2e688770c65 --- /dev/null +++ b/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 diff --git a/console/style.rst b/console/style.rst index 0aaaa3f675e..e1e5df38ffe 100644 --- a/console/style.rst +++ b/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