Skip to content

Commit 568392f

Browse files
weaverryanweaverryan
committed
Merge branch '2.0' into 2.1
2 parents ec46d85 + 432b8a5 commit 568392f

File tree

8 files changed

+195
-62
lines changed

8 files changed

+195
-62
lines changed

‎components/console/helpers/dialoghelper.rst

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
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 the
15+
argument, the question as the second argument and the default value as last
16+
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 you 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 will return
34+
``true`` if the user answers with ``y`` or false in any other case. The third
35+
argument to ``askConfirmation`` is the default value to return if the user doesn't
36+
enter 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+
if 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". She can type
52+
some name which will be returned by the ``ask`` method. If she leaves it empty,
53+
the default value (``AcmeDemoBundle`` here) is returned.
54+
55+
Validating the Answer
56+
---------------------
57+
58+
You can even validate the answer. For instance, in the last example you asked
59+
for the bundle name. Following the Symfony2 naming conventions, it should
60+
be suffixed with ``Bundle``. You 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 is displayed
91+
in the console, so it is a good practice to put some useful information
92+
in it.
93+
94+
You can set the max number of times to ask in the ``$attempts`` argument.
95+
If you reach this max number it will use the default value, which is given
96+
in the last argument. Using ``false`` means the amount of attempts is infinite.
97+
The user will be asked as long as he provides an invalid answer and will only
98+
be able to proceed if her input is valid.

‎components/console/helpers/formatterhelper.rst

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
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 you can 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 you'll usually render to the console by
18+
passing it to the
19+
:method:`OutputInterface::writeln<Symfony\\Component\\Console\\Output\\OutputInterface::writeln>` method.
20+
21+
Print Messages in a Section
22+
---------------------------
23+
24+
Symfony offers a defined style when printing a message that belongs to some
25+
"section". It prints the section in color and with brackets around it and the
26+
actual message to the right of this. Minus the color, it looks like this:
27+
28+
.. code-block:: text
29+
30+
[SomeSection] Here is some message related to that section
31+
32+
To reproduce this style, you can use the
33+
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatSection`
34+
method::
35+
36+
$formattedLine = $formatter->formatSection(
37+
'SomeSection',
38+
'Here is some message related to that section'
39+
);
40+
$output->writeln($formattedLine);
41+
42+
Print Messages in a Block
43+
-------------------------
44+
45+
Sometimes you want to be able to print a whole block of text with a background
46+
color. Symfony uses this when printing error messages.
47+
48+
If you print your error message on more than one line manually, you will
49+
notice that the background is only as long as each individual line. Use the
50+
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
51+
to generate a block output::
52+
53+
$errorMessages = array('Error!', 'Something went wrong');
54+
$formattedBlock = $formatter->formatBlock($errorMessages, 'error');
55+
$output->writeln($formattedBlock);
56+
57+
As you can see, passing an array of messages to the
58+
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
59+
method creates the desired output. If you pass ``true`` as third parameter, the
60+
block will be formatted with more padding (one blank line above and below the
61+
messages and 2 spaces on the left and right).
62+
63+
The exact "style" you use in the block is up to you. In this case, you're using
64+
the pre-defined ``error`` style, but there are other styles, or you can create
65+
your own. See :ref:`components-console-coloring`.

‎components/console/helpers/index.rst

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

‎components/console/helpers/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: 8 additions & 61 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,69 +269,14 @@ 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-
---------------------------------------
272+
Console Helpers
273+
---------------
304274

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-
}
275+
The console component also contains a set of "helpers" - different small
276+
tools capable of helping you with different tasks:
316277

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).
278+
* :doc:`/components/console/helpers/dialoghelper`: interactively ask the user for information
279+
* :doc:`/components/console/helpers/formatterhelper`: customize the output colorization
333280

334281
Testing Commands
335282
----------------

‎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

‎components/security/introduction.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,13 @@ Installation
2020
You can install the component in many different ways:
2121

2222
* Use the official Git repository (https://github.com/symfony/Security);
23-
* :doc:`Install it via Composer</components/using_components>` (``symfony/security`` on `Packagist`_).
23+
* :doc:`Install it via Composer</components/using_components>` (`symfony/security`_ on Packagist).
2424

2525
Sections
2626
--------
2727

2828
* :doc:`/components/security/firewall`
2929
* :doc:`/components/security/authentication`
3030
* :doc:`/components/security/authorization`
31+
32+
.. _symfony/security: https://packagist.org/packages/symfony/security

0 commit comments

Comments
 (0)