From 603f6aa734f95d302034bb4e037a765e43acf698 Mon Sep 17 00:00:00 2001 From: Alexandre Daubois Date: Tue, 18 Jul 2023 17:20:53 +0200 Subject: [PATCH] [Console] Add `ProgressIndicator` page --- components/console/helpers/progressbar.rst | 6 + .../console/helpers/progressindicator.rst | 126 ++++++++++++++++++ console.rst | 1 + 3 files changed, 133 insertions(+) create mode 100644 components/console/helpers/progressindicator.rst diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index fb3f2acfe7b..3e43452a737 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -81,6 +81,12 @@ The progress will then be displayed as a throbber: 1/3 [=========>------------------] 33% 3/3 [============================] 100% +.. tip:: + + An alternative to this is to use a + :doc:`/components/console/helpers/progressindicator` instead of a + progress bar. + Whenever your task is finished, don't forget to call :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::finish` to ensure that the progress bar display is refreshed with a 100% completion. diff --git a/components/console/helpers/progressindicator.rst b/components/console/helpers/progressindicator.rst new file mode 100644 index 00000000000..9cd82b0aed1 --- /dev/null +++ b/components/console/helpers/progressindicator.rst @@ -0,0 +1,126 @@ +Progress Indicator +================== + +When executing longer-running commands without knowing if the the processing +is nearly done or not, it may be helpful to show that something is actually +happening and that updates as your command runs. + +To do so, use the +:class:`Symfony\\Component\\Console\\Helper\\ProgressIndicator` and advance the +progress as the command executes:: + + use Symfony\Component\Console\Helper\ProgressIndicator; + + // creates a new progress indicator + $progressIndicator = new ProgressIndicator($output); + + // starts and displays the progress indicator with a custom message + $progressIndicator->start('Processing...'); + + $i = 0; + while ($i++ < 50) { + // ... do some work + + // advances the progress indicator + $progressIndicator->advance(); + } + + // ensures that the progress indicator shows a final message + $progressIndicator->finish('Finished'); + +Customizing the Progress Indicator +---------------------------------- + +Built-in Formats +~~~~~~~~~~~~~~~~ + +By default, the information rendered on a progress indicator depends on the current +level of verbosity of the ``OutputInterface`` instance: + +.. code-block:: text + + # OutputInterface::VERBOSITY_NORMAL (CLI with no verbosity flag) + \ Processing... + | Processing... + / Processing... + - Processing... + + # OutputInterface::VERBOSITY_VERBOSE (-v) + \ Processing... (1 sec) + | Processing... (1 sec) + / Processing... (1 sec) + - Processing... (1 sec) + + # OutputInterface::VERBOSITY_VERY_VERBOSE (-vv) and OutputInterface::VERBOSITY_DEBUG (-vvv) + \ Processing... (1 sec, 6.0 MiB) + | Processing... (1 sec, 6.0 MiB) + / Processing... (1 sec, 6.0 MiB) + - Processing... (1 sec, 6.0 MiB) + +.. note:: + + If you call a command with the quiet flag (``-q``), the progress indicator won't + be displayed. + +Instead of relying on the verbosity mode of the current command, you can also +force a format via the second argument of the ``ProgressIndicator`` +constructor:: + + $progressIndicator = new ProgressIndicator($output, 'verbose'); + +The built-in formats are the following: + +* ``normal`` +* ``verbose`` +* ``very_verbose`` + +If your terminal doesn't support ANSI, use the ``no_ansi`` variants: + +* ``normal_no_ansi`` +* ``verbose_no_ansi`` +* ``very_verbose_no_ansi`` + +Custom Indicator Values +~~~~~~~~~~~~~~~~~~~~~~~ + +Instead of using the built-in indicator values, you can also set your own:: + + $progressIndicator = new ProgressIndicator($output, 'verbose', 100, ['⠏', '⠛', '⠹', '⢸', '⣰', '⣤', '⣆', '⡇']); + +The progress indicator will now look like this: + +.. code-block:: text + + ⠏ Processing... + ⠛ Processing... + ⠹ Processing... + ⢸ Processing... + +Customize Placeholders +~~~~~~~~~~~~~~~~~~~~~~ + +A progress indicator uses placeholders (a name enclosed with the ``%`` +character) to determine the output format. Here is a list of the +built-in placeholders: + +* ``indicator``: The current indicator; +* ``elapsed``: The time elapsed since the start of the progress indicator; +* ``memory``: The current memory usage; +* ``message``: used to display arbitrary messages in the progress indicator. + +If you want to customize a placeholder, for example the ``message`` one, here +is how you should do this:: + + ProgressIndicator::setPlaceholderFormatterDefinition( + 'message', + static function (ProgressIndicator $progressIndicator): string { + // Return any arbitrary string + return 'My custom message'; + } + ); + +.. note:: + + Placeholders customization is applied globally, which means that any + progress indicator displayed after the + ``setPlaceholderFormatterDefinition()`` call will be affected. diff --git a/console.rst b/console.rst index 04c53fddae9..4078bfc221d 100644 --- a/console.rst +++ b/console.rst @@ -587,6 +587,7 @@ tools capable of helping you with different tasks: * :doc:`/components/console/helpers/questionhelper`: interactively ask the user for information * :doc:`/components/console/helpers/formatterhelper`: customize the output colorization * :doc:`/components/console/helpers/progressbar`: shows a progress bar +* :doc:`/components/console/helpers/progressindicator`: shows a progress indicator * :doc:`/components/console/helpers/table`: displays tabular data as a table * :doc:`/components/console/helpers/debug_formatter`: provides functions to output debug information when running an external program