Skip to content

Commit 3e6b5ec

Browse files
weaverryanweaverryan
committed
Merge branch 'issue1811' of github.com:Sgoettschkes/symfony-docs into Sgoettschkes-issue1811
Conflicts: components/console/introduction.rst
2 parents 3ab0a5c + b85a526 commit 3e6b5ec

File tree

7 files changed

+172
-64
lines changed

7 files changed

+172
-64
lines changed

‎components/console/helpers/dialoghelper.rst

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
.. index::
2+
single: Console Helpers; Dialog Helper
3+
4+
Dialog Helper
5+
=============
6+
7+
The Dialog Helper provides functions to ask the user for more information.
8+
It is included in the default helper set, which you can get
9+
by calling :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
10+
11+
$dialog = $this->getHelperSet()->get('dialog');
12+
13+
All the methods inside the Dialog Helper have an
14+
:class:`Symfony\\Component\\Console\\Output\\OutputInterface` as first argument,
15+
the question as second argument and the default value as last argument.
16+
17+
Asking the User for confirmation
18+
--------------------------------
19+
20+
Suppose you want to confirm an action before actually executing it. Add
21+
the following to your command::
22+
23+
// ...
24+
if (!$dialog->askConfirmation(
25+
$output,
26+
'<question>Continue with this action?</question>',
27+
false
28+
)) {
29+
return;
30+
}
31+
32+
In this case, the user will be asked "Continue with this action", and will return
33+
``true`` if the user answers with ``y`` or false in any other case. The third
34+
argument to ``askConfirmation`` is the default value to return if the user doesn't
35+
enter any input.
36+
37+
Asking the User for information
38+
-------------------------------
39+
40+
You can also ask question with more than a simple yes/no answer. For instance,
41+
if you want to know a bundle name, you can add this to your command::
42+
43+
// ...
44+
$bundle = $dialog->ask(
45+
$output,
46+
'Please enter the name of the bundle',
47+
'AcmeDemoBundle'
48+
);
49+
50+
The user will be asked "Please enter the name of the bundle". They can type
51+
some name which will be returned by the ``ask`` method. If they leave it empty
52+
the default value (``AcmeDemoBundle`` here) is returned.
53+
54+
Validating the answer
55+
---------------------
56+
57+
You can even validate the answer. For instance, in our last example we asked
58+
for the bundle name. Following the Symfony2 naming conventions, it should
59+
be suffixed with ``Bundle``. We can validate that by using the
60+
:method:`Symfony\\Component\\Console\\Helper\\DialogHelper::askAndValidate`
61+
method::
62+
63+
// ...
64+
$bundle = $dialog->askAndValidate(
65+
$output,
66+
'Please enter the name of the bundle',
67+
function ($answer) {
68+
if ('Bundle' !== substr($answer, -6)) {
69+
throw new \RunTimeException(
70+
'The name of the bundle should be suffixed with \'Bundle\''
71+
);
72+
}
73+
},
74+
false,
75+
'AcmeDemoBundle'
76+
);
77+
78+
This methods has 2 new arguments, the full signature is::
79+
80+
askAndValidate(
81+
OutputInterface $output,
82+
string|array $question,
83+
callback $validator,
84+
integer $attempts = false,
85+
string $default = null
86+
)
87+
88+
The ``$validator`` is a callback which handles the validation. It should
89+
throw an exception if there is something wrong. The exception message is displayed
90+
in the console, so it is a good practice to put some usefull information
91+
in it.
92+
93+
You can set the max number of times to ask in the ``$attempts`` argument.
94+
If we reach this max number it will use the default value, which is given
95+
in the last argument. Using ``false`` means the amount of attempts is infinite.
96+
The user will be asked as long as he provides an invalid answer and will only
97+
be able to proceed if his input is valid.

‎components/console/helpers/formatterhelper.rst

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. index::
2+
single: Console Helpers; Formatter Helper
3+
4+
Formatter Helper
5+
================
6+
7+
The Formatter helpers provides functions to format the output with colors.
8+
You can do more advanced things with this helper than the things in
9+
:ref:`components-console-coloring`.
10+
11+
The Formatter Helper is included in the default helper set, which you can
12+
get by calling
13+
:method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
14+
15+
$formatter = $this->getHelperSet()->get('formatter');
16+
17+
The methods return a string which in most cases you want to write
18+
that data to the console with
19+
:method:`Symfony\\Component\\Console\\Output\\Output::writeln`.
20+
21+
Print messages in a section
22+
---------------------------
23+
24+
Symfony uses a defined style when printing to the command line.
25+
It prints the section in color and with brackets around and the
26+
actual message behind this section indication.
27+
28+
To reproduce this style, you can use the
29+
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatSection`::
30+
31+
$formattedLine = $formatter->formatSection('SomeCommand', 'Some output from within the SomeCommand');
32+
$output->writeln($formattedLine);
33+
34+
Print messages in a block
35+
-------------------------
36+
37+
Sometimes you want to be able to print a whole block of text with a background
38+
color. Symfony uses this when printing error messages.
39+
40+
If you print your error message on more than one line manually, you will
41+
notice that the background is only as long as each individual line. Use the
42+
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
43+
togenerate a block output::
44+
45+
$errorMessages = array('Error!', 'Something went wrong');
46+
$formattedBlock = $formatter->formatBlock($errorMessages, 'error');
47+
48+
As you can see, passing an array of messages to the
49+
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
50+
method creates the desired output. If you pass ``true`` as third parameter, the
51+
block will be formatted with more padding (one blank line above and below the
52+
messages and 2 spaces on the left and right).

‎components/console/helpers/index.rst

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. index::
2+
single: Console; Console Helpers
3+
4+
The Console Helpers
5+
===================
6+
7+
.. toctree::
8+
:hidden:
9+
10+
dialoghelper
11+
formatterhelper
12+
13+
The Console Components comes with some usefull helpers. These helpers contain
14+
function to ease some common tasks.
15+
16+
.. include:: map.rst.inc

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

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

‎components/console/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,5 @@ Console
77
introduction
88
usage
99
single_command_tool
10+
11+
helpers/index

‎components/console/introduction.rst

+2-64
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,8 @@ This prints::
108108

109109
HELLO FABIEN
110110

111+
.. _components-console-coloring:
112+
111113
Coloring the Output
112114
~~~~~~~~~~~~~~~~~~~
113115

@@ -267,70 +269,6 @@ You can combine VALUE_IS_ARRAY with VALUE_REQUIRED or VALUE_OPTIONAL like this:
267269
1
268270
);
269271
270-
Asking the User for Information
271-
-------------------------------
272-
273-
When creating commands, you have the ability to collect more information
274-
from the user by asking him/her questions. For example, suppose you want
275-
to confirm an action before actually executing it. Add the following to your
276-
command::
277-
278-
$dialog = $this->getHelperSet()->get('dialog');
279-
if (!$dialog->askConfirmation(
280-
$output,
281-
'<question>Continue with this action?</question>',
282-
false
283-
)) {
284-
return;
285-
}
286-
287-
In this case, the user will be asked "Continue with this action", and unless
288-
they answer with ``y``, the task will stop running. The third argument to
289-
``askConfirmation`` is the default value to return if the user doesn't enter
290-
any input.
291-
292-
You can also ask questions with more than a simple yes/no answer. For example,
293-
if you needed to know the name of something, you might do the following::
294-
295-
$dialog = $this->getHelperSet()->get('dialog');
296-
$name = $dialog->ask(
297-
$output,
298-
'Please enter the name of the widget',
299-
'foo'
300-
);
301-
302-
Ask Questions and validate the Response
303-
---------------------------------------
304-
305-
You can easily ask a question and validate the response with built-in methods::
306-
307-
$dialog = $this->getHelperSet()->get('dialog');
308-
309-
$validator = function ($value) {
310-
if ('' === trim($value)) {
311-
throw new \Exception('The value can not be empty');
312-
}
313-
314-
return $value;
315-
}
316-
317-
$password = $dialog->askAndValidate(
318-
$output,
319-
'Please enter the name of the widget',
320-
$validator,
321-
20,
322-
'foo'
323-
);
324-
325-
The validation callback can be any callable PHP function and the fourth argument
326-
to :method:`Symfony\\Component\\Console\\Helper::askAndValidate` is the maximum
327-
number of attempts - set it to ``false`` (the default value) for unlimited
328-
attempts. The fifth argument is the default value.
329-
330-
The callback must throw an exception in case the value is not acceptable. Please
331-
note that the callback **must** return the value. The value can be modified by
332-
the callback (it will be returned modified by the helper).
333-
334272
Testing Commands
335273
----------------
336274

‎components/map.rst.inc

+1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
* :doc:`/components/console/introduction`
1717
* :doc:`/components/console/usage`
1818
* :doc:`/components/console/single_command_tool`
19+
* :doc:`/components/console/helpers/index`
1920

2021
* **CSS Selector**
2122

0 commit comments

Comments
 (0)