Skip to content

Commit d162a5c

Browse files
wouterjwouterj
committed
Created DialogHelper documentation
1 parent 7f5a626 commit d162a5c

File tree

4 files changed

+101
-33
lines changed

4 files changed

+101
-33
lines changed

‎components/console/helpers/dialoghelper.rst

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

‎components/console/helpers/index.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ Console Helpers
77
.. toctree::
88
:maxdepth: 2
99

10+
dialoghelper
11+
12+
1013
The Console Components comes with some usefull helpers. These helpers contain
1114
function to ease some common tasks.
1215

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* :doc:`/components/console/helpers/dialoghelper`

‎components/console/introduction.rst

Lines changed: 1 addition & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -255,38 +255,6 @@ You can combine VALUE_IS_ARRAY with VALUE_REQUIRED or VALUE_OPTIONAL like this:
255255
1
256256
);
257257
258-
Asking the User for Information
259-
-------------------------------
260-
261-
When creating commands, you have the ability to collect more information
262-
from the user by asking him/her questions. For example, suppose you want
263-
to confirm an action before actually executing it. Add the following to your
264-
command::
265-
266-
$dialog = $this->getHelperSet()->get('dialog');
267-
if (!$dialog->askConfirmation(
268-
$output,
269-
'<question>Continue with this action?</question>',
270-
false
271-
)) {
272-
return;
273-
}
274-
275-
In this case, the user will be asked "Continue with this action", and unless
276-
they answer with ``y``, the task will stop running. The third argument to
277-
``askConfirmation`` is the default value to return if the user doesn't enter
278-
any input.
279-
280-
You can also ask questions with more than a simple yes/no answer. For example,
281-
if you needed to know the name of something, you might do the following::
282-
283-
$dialog = $this->getHelperSet()->get('dialog');
284-
$name = $dialog->ask(
285-
$output,
286-
'Please enter the name of the widget',
287-
'foo'
288-
);
289-
290258
Testing Commands
291259
----------------
292260

@@ -407,4 +375,4 @@ Learn More!
407375
* :doc:`/components/console/usage`
408376
* :doc:`/components/console/single_command_tool`
409377

410-
.. _Packagist: https://packagist.org/packages/symfony/console
378+
.. _Packagist: https://packagist.org/packages/symfony/console

0 commit comments

Comments
 (0)