Skip to content

Commit 87710a8

Browse files
weaverryanweaverryan
committed
Merge pull request #2074 from Sgoettschkes/issue2022
Components/Console improvements
2 parents c926dae + f002cea commit 87710a8

File tree

5 files changed

+114
-71
lines changed

5 files changed

+114
-71
lines changed

‎components/console/helpers/dialoghelper.rst

+38
Original file line numberDiff line numberDiff line change
@@ -149,3 +149,41 @@ You can also ask and validate a hidden response::
149149

150150
If you want to allow the response to be visible if it cannot be hidden for
151151
some reason, pass true as the fifth argument.
152+
153+
Let the user choose from a list of answers
154+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155+
156+
.. versionadded:: 2.2
157+
The ``select`` method was added in Symfony 2.2.
158+
159+
If you have a predefined set of answers the user can choose from, you
160+
could use the ``ask`` method described above or, to make sure the user
161+
provided a correct answer, the ``askAndValidate`` method. Both have
162+
the disadvantage that you need to handle incorrect values yourself.
163+
164+
Instead, you can use the
165+
:method:`Symfony\\Component\\Console\\Helper\\DialogHelper::select`
166+
method, which makes sure that the user can only enter a valid string
167+
from a predefined list::
168+
169+
$dialog = $app->getHelperSet()->get('dialog');
170+
$colors = array('red', 'blue', 'yellow');
171+
172+
$color = $dialog->select(
173+
$output,
174+
'Please select your favorite color (default to red)',
175+
$colors,
176+
0
177+
);
178+
$output->writeln('You have just selected: ' . $colors[$color]);
179+
180+
// ... do something with the color
181+
182+
The option which should be selected by default is provided with the fourth
183+
parameter. The default is ``null``, which means that no option is the default one.
184+
185+
If the user enters an invalid string, an error message is shown and the user
186+
is asked to provide the answer another time, till he enters a valid string
187+
or the maximum attempts is reached (which you can define in the fifth
188+
parameter). The default value for the attempts is ``false``, which means infinite
189+
attempts. You can define your own error message in the sixth parameter.

‎components/console/helpers/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ The Console Helpers
99

1010
dialoghelper
1111
formatterhelper
12+
progresshelper
1213

1314
The Console Components comes with some usefull helpers. These helpers contain
1415
function to ease some common tasks.

‎components/console/helpers/map.rst.inc

+1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
* :doc:`/components/console/helpers/dialoghelper`
22
* :doc:`/components/console/helpers/formatterhelper`
3+
* :doc:`/components/console/helpers/progresshelper`

‎components/console/helpers/progresshelper.rst

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
.. index::
2+
single: Console Helpers; Progress Helper
3+
4+
Progress Helper
5+
===============
6+
7+
.. versionadded:: 2.2
8+
The ``progress`` helper was added in Symfony 2.2.
9+
10+
When executing longer-running commands, it may be helpful to show progress
11+
information, which updates as your command runs:
12+
13+
.. image:: /images/components/console/progress.png
14+
15+
To display progress details, use the :class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`,
16+
pass it a total number of units, and advance the progress as your command executes::
17+
18+
$progress = $this->getHelperSet()->get('progress');
19+
20+
$progress->start($output, 50);
21+
$i = 0;
22+
while ($i++ < 50) {
23+
// ... do some work
24+
25+
// advance the progress bar 1 unit
26+
$progress->advance();
27+
}
28+
29+
$progress->finish();
30+
31+
The appearance of the progress output can be customized as well, with a number
32+
of different levels of verbosity. Each of these displays different possible
33+
items - like percentage completion, a moving progress bar, or current/total
34+
information (e.g. 10/50)::
35+
36+
$progress->setFormat(ProgressHelper::FORMAT_QUIET);
37+
$progress->setFormat(ProgressHelper::FORMAT_NORMAL);
38+
$progress->setFormat(ProgressHelper::FORMAT_VERBOSE);
39+
$progress->setFormat(ProgressHelper::FORMAT_QUIET_NOMAX);
40+
// the default value
41+
$progress->setFormat(ProgressHelper::FORMAT_NORMAL_NOMAX);
42+
$progress->setFormat(ProgressHelper::FORMAT_VERBOSE_NOMAX);
43+
44+
You can also control the different characters and the width used for the
45+
progress bar::
46+
47+
// the finished part of the bar
48+
$progress->setBarCharacter('<comment>=</comment>');
49+
// the unfinished part of the bar
50+
$progress->setEmptyBarCharacter(' ');
51+
$progress->setProgressCharacter('|');
52+
$progress->setBarWidth(50);
53+
54+
To see other available options, check the API documentation for
55+
:class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`.
56+
57+
.. caution::
58+
59+
For performance reasons, be careful to not set the total number of steps
60+
to a high number. For example, if you're iterating over a large number
61+
of items, consider a smaller "step" number that updates on only some
62+
iterations::
63+
64+
$progress->start($output, 500);
65+
$i = 0;
66+
while ($i++ < 50000) {
67+
// ... do some work
68+
69+
// advance every 100 iterations
70+
if ($i % 100 == 0) {
71+
$progress->advance();
72+
}
73+
}

‎components/console/introduction.rst

+1-71
Original file line numberDiff line numberDiff line change
@@ -278,77 +278,6 @@ You can combine VALUE_IS_ARRAY with VALUE_REQUIRED or VALUE_OPTIONAL like this:
278278
1
279279
);
280280
281-
Displaying a Progress Bar
282-
-------------------------
283-
284-
.. versionadded:: 2.2
285-
The ``progress`` helper was added in Symfony 2.2.
286-
287-
When executing longer-running commands, it may be helpful to show progress
288-
information, which updates as your command runs:
289-
290-
.. image:: /images/components/console/progress.png
291-
292-
To display progress details, use the :class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`,
293-
pass it a total number of units, and advance the progress as your command executes::
294-
295-
$progress = $this->getHelperSet()->get('progress');
296-
297-
$progress->start($output, 50);
298-
$i = 0;
299-
while ($i++ < 50) {
300-
// do some work
301-
302-
// advance the progress bar 1 unit
303-
$progress->advance();
304-
}
305-
306-
$progress->finish();
307-
308-
The appearance of the progress output can be customized as well, with a number
309-
of different levels of verbosity. Each of these displays different possible
310-
items - like percentage completion, a moving progress bar, or current/total
311-
information (e.g. 10/50)::
312-
313-
$progress->setFormat(ProgressHelper::FORMAT_QUIET);
314-
$progress->setFormat(ProgressHelper::FORMAT_NORMAL);
315-
$progress->setFormat(ProgressHelper::FORMAT_VERBOSE);
316-
$progress->setFormat(ProgressHelper::FORMAT_QUIET_NOMAX);
317-
// the default value
318-
$progress->setFormat(ProgressHelper::FORMAT_NORMAL_NOMAX);
319-
$progress->setFormat(ProgressHelper::FORMAT_VERBOSE_NOMAX);
320-
321-
You can also control the different characters and the width used for the
322-
progress bar::
323-
324-
// the finished part of the bar
325-
$progress->setBarCharacter('<comment>=</comment>');
326-
// the unfinished part of the bar
327-
$progress->setEmptyBarCharacter(' ');
328-
$progress->setProgressCharacter('|');
329-
$progress->setBarWidth(50);
330-
331-
To see other available options, check the API documentation for
332-
:class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`.
333-
334-
.. caution::
335-
336-
For performance reasons, be careful to not set the total number of steps
337-
to a high number. For example, if you're iterating over a large number
338-
of items, consider a smaller "step" number that updates on only some
339-
iterations::
340-
341-
$progress->start($output, 500);
342-
$i = 0;
343-
while ($i++ < 50000) {
344-
// ... do some work
345-
346-
// advance every 100 iterations
347-
if ($i % 100 == 0) {
348-
$progress->advance();
349-
}
350-
}
351-
352281
Console Helpers
353282
---------------
354283

@@ -357,6 +286,7 @@ tools capable of helping you with different tasks:
357286

358287
* :doc:`/components/console/helpers/dialoghelper`: interactively ask the user for information
359288
* :doc:`/components/console/helpers/formatterhelper`: customize the output colorization
289+
* :doc:`/components/console/helpers/progresshelper`: shows a progress bar
360290

361291
Testing Commands
362292
----------------

0 commit comments

Comments
 (0)