Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit3e6b5ec

Browse files
committed
Merge branch 'issue1811' of github.com:Sgoettschkes/symfony-docs into Sgoettschkes-issue1811
Conflicts:components/console/introduction.rst
2 parents3ab0a5c +b85a526 commit3e6b5ec

File tree

7 files changed

+172
-64
lines changed

7 files changed

+172
-64
lines changed
Lines changed: 97 additions & 0 deletions
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.
Lines changed: 52 additions & 0 deletions
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).
Lines changed: 16 additions & 0 deletions
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
Lines changed: 2 additions & 0 deletions
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‎

Lines changed: 2 additions & 0 deletions
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‎

Lines changed: 2 additions & 64 deletions
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‎

Lines changed: 1 addition & 0 deletions
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)
[8]ページ先頭
©2009-2025 Movatter.jp