10000 [Console] Add `ProgressIndicator` page · symfony/symfony-docs@603f6aa · GitHub
[go: up one dir, main page]
Skip to content

Commit 603f6aa

Browse files
alexandre-dauboisalexandre-daubois
committed
[Console] Add ProgressIndicator page
1 parent ffb2cc1 commit 603f6aa

File tree

3 files changed

+133
-0
lines changed

3 files changed

+133
-0
lines changed

‎components/console/helpers/progressbar.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,12 @@ The progress will then be displayed as a throbber:
8181
1/3 [=========>------------------] 33%
8282
3/3 [============================] 100%
8383
84+
.. tip::
85+
86+
An alternative to this is to use a
87+
:doc:`/components/console/helpers/progressindicator` instead of a
88+
progress bar.
89+
8490
Whenever your task is finished, don't forget to call
8591
:method:`Symfony\\Component\\Console\\Helper\\ProgressBar::finish` to ensure
8692
that the progress bar display is refreshed with a 100% completion.

‎components/console/helpers/progressindicator.rst

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
Progress Indicator
2+
==================
3+
4+
When executing longer-running commands without knowing if the the processing
5+
is nearly done or not, it may be helpful to show that something is actually
6+
happening and that updates as your command runs.
7+
8+
To do so, use the
9+
:class:`Symfony\\Component\\Console\\Helper\\ProgressIndicator` and advance the
10+
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+
.. note::
61+
62+
If you call a command with the quiet flag (``-q``), the progress indicator won't
63+
be displayed.
64+
65+
Instead of relying on the verbosity mode of the current command, you can also
66+
force a format via the second argument of the ``ProgressIndicator``
67+
constructor::
68+
69+
$progressIndicator = new ProgressIndicator($output, 'verbose');
70+
71+
The built-in formats are the following:
72+
73+
* ``normal``
74+
* ``verbose``
75+
* ``very_verbose``
76+
77+
If your terminal doesn't support ANSI, use the ``no_ansi`` variants:
78+
79+
* ``normal_no_ansi``
80+
* ``verbose_no_ansi``
81+
* ``very_verbose_no_ansi``
82+
83+
Custom Indicator Values
84+
~~~~~~~~~~~~~~~~~~~~~~~
85+
86+
Instead of using the built-in indicator values, you can also set your own::
87+
88+
$progressIndicator = new ProgressIndicator($output, 'verbose', 100, ['⠏', '⠛', '⠹', '⢸', '⣰', '⣤', '⣆', '⡇']);
89+
90+
The progress indicator will now look like this:
91+
92+
.. code-block:: text
93+
94+
⠏ Processing...
95+
⠛ Processing...
96+
⠹ Processing...
97+
⢸ Processing...
98+
99+
Customize Placeholders
100+
~~~~~~~~~~~~~~~~~~~~~~
101+
102+
A progress indicator uses placeholders (a name enclosed with the ``%``
103+
character) to determine the output format. Here is a list of the
104+
built-in placeholders:
105+
106+
* ``indicator``: The current indicator;
107+
* ``elapsed``: The time elapsed since the start of the progress indicator;
108+
* ``memory``: The current memory usage;
109+
* ``message``: used to display arbitrary messages in the progress indicator.
110+
111+
If you want to customize a placeholder, for example the ``message`` one, here
112+
is how you should do this::
113+
114+
ProgressIndicator::setPlaceholderFormatterDefinition(
115+
'message',
116+
static function (ProgressIndicator $progressIndicator): string {
117+
// Return any arbitrary string
118+
return 'My custom message';
119+
}
120+
);
121+
122+
.. note::
123+
124+
Placeholders customization is applied globally, which means that any
125+
progress indicator displayed after the
126+
``setPlaceholderFormatterDefinition()`` call will be affected.

‎console.rst

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

0 commit comments

Comments
 (0)
0