Skip to content

Commit 50d8f5a

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '5.4' into 6.2
* 5.4: [Console] Add `ProgressIndicator` page
2 parents 64a13d5 + 57bf707 commit 50d8f5a

File tree

3 files changed

+131
-0
lines changed

3 files changed

+131
-0
lines changed

‎components/console/helpers/progressbar.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,12 @@ The progress will then be displayed as a throbber:
9797
1/3 [=========>------------------] 33%
9898
3/3 [============================] 100%
9999
100+
.. tip::
101+
102+
An alternative to this is to use a
103+
:doc:`/components/console/helpers/progressindicator` instead of a
104+
progress bar.
105+
100106
Whenever your task is finished, don't forget to call
101107
:method:`Symfony\\Component\\Console\\Helper\\ProgressBar::finish` to ensure
102108
that the progress bar display is refreshed with a 100% completion.

‎components/console/helpers/progressindicator.rst

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
Progress Indicator
2+
==================
3+
4+
Progress indicators are useful to let users know that a command isn't stalled.
5+
Unlike :doc:`progress bars </components/console/helpers/progressbar>`, these
6+
indicators are used when the command duration is indeterminate (e.g. long-running
7+
commands, unquantifiable tasks, etc.)
8+
9+
They work by instantiating the :class:`Symfony\\Component\\Console\\Helper\\ProgressIndicator`
10+
class and advancing the progress as the command executes::
11+
12+
use Symfony\Component\Console\Helper\ProgressIndicator;
13+
14+
// creates a new progress indicator
15+
$progressIndicator = new ProgressIndicator($output);
16+
17+
// starts and displays the progress indicator with a custom message
18+
$progressIndicator->start('Processing...');
19+
20+
$i = 0;
21+
while ($i++ < 50) {
22+
// ... do some work
23+
24+
// advances the progress indicator
25+
$progressIndicator->advance();
26+
}
27+
28+
// ensures that the progress indicator shows a final message
29+
$progressIndicator->finish('Finished');
30+
31+
Customizing the Progress Indicator
32+
----------------------------------
33+
34+
Built-in Formats
35+
~~~~~~~~~~~~~~~~
36+
37+
By default, the information rendered on a progress indicator depends on the current
38+
level of verbosity of the ``OutputInterface`` instance:
39+
40+
.. code-block:: text
41+
42+
# OutputInterface::VERBOSITY_NORMAL (CLI with no verbosity flag)
43+
\ Processing...
44+
| Processing...
45+
/ Processing...
46+
- Processing...
47+
48+
# OutputInterface::VERBOSITY_VERBOSE (-v)
49+
\ Processing... (1 sec)
50+
| Processing... (1 sec)
51+
/ Processing... (1 sec)
52+
- Processing... (1 sec)
53+
54+
# OutputInterface::VERBOSITY_VERY_VERBOSE (-vv) and OutputInterface::VERBOSITY_DEBUG (-vvv)
55+
\ Processing... (1 sec, 6.0 MiB)
56+
| Processing... (1 sec, 6.0 MiB)
57+
/ Processing... (1 sec, 6.0 MiB)
58+
- Processing... (1 sec, 6.0 MiB)
59+
60+
.. tip::
61+
62+
Call a command with the quiet flag (``-q``) to not display any progress indicator.
63+
64+
Instead of relying on the verbosity mode of the current command, you can also
65+
force a format via the second argument of the ``ProgressIndicator``
66+
constructor::
67+
68+
$progressIndicator = new ProgressIndicator($output, 'verbose');
69+
70+
The built-in formats are the following:
71+
72+
* ``normal``
73+
* ``verbose``
74+
* ``very_verbose``
75+
76+
If your terminal doesn't support ANSI, use the ``no_ansi`` variants:
77+
78+
* ``normal_no_ansi``
79+
* ``verbose_no_ansi``
80+
* ``very_verbose_no_ansi``
81+
82+
Custom Indicator Values
83+
~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
Instead of using the built-in indicator values, you can also set your own::
86+
87+
$progressIndicator = new ProgressIndicator($output, 'verbose', 100, ['⠏', '⠛', '⠹', '⢸', '⣰', '⣤', '⣆', '⡇']);
88+
89+
The progress indicator will now look like this:
90+
91+
.. code-block:: text
92+
93+
⠏ Processing...
94+
⠛ Processing...
95+
⠹ Processing...
96+
⢸ Processing...
97+
98+
Customize Placeholders
99+
~~~~~~~~~~~~~~~~~~~~~~
100+
101+
A progress indicator uses placeholders (a name enclosed with the ``%``
102+
character) to determine the output format. Here is a list of the
103+
built-in placeholders:
104+
105+
* ``indicator``: The current indicator;
106+
* ``elapsed``: The time elapsed since the start of the progress indicator;
107+
* ``memory``: The current memory usage;
108+
* ``message``: used to display arbitrary messages in the progress indicator.
109+
110+
For example, this is how you can customize the ``message`` placeholder::
111+
112+
ProgressIndicator::setPlaceholderFormatterDefinition(
113+
'message',
114+
static function (ProgressIndicator $progressIndicator): string {
115+
// Return any arbitrary string
116+
return 'My custom message';
117+
}
118+
);
119+
120+
.. note::
121+
122+
Placeholders customization is applied globally, which means that any
123+
progress indicator displayed after the
124+
``setPlaceholderFormatterDefinition()`` call will be affected.

‎console.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -579,6 +579,7 @@ tools capable of helping you with different tasks:
579579
* :doc:`/components/console/helpers/questionhelper`: interactively ask the user for information
580580
* :doc:`/components/console/helpers/formatterhelper`: customize the output colorization
581581
* :doc:`/components/console/helpers/progressbar`: shows a progress bar
582+
* :doc:`/components/console/helpers/progressindicator`: shows a progress indicator
582583
* :doc:`/components/console/helpers/table`: displays tabular data as a table
583584
* :doc:`/components/console/helpers/debug_formatter`: provides functions to
584585
output debug information when running an external program

0 commit comments

Comments
 (0)