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

Documenting the Console Helpers#1999

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
weaverryan merged 7 commits intosymfony:2.0fromSgoettschkes:issue1811
Dec 26, 2012
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 97 additions & 0 deletionscomponents/console/helpers/dialoghelper.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
.. index::
single: Console Helpers; Dialog Helper

Dialog Helper
=============

The Dialog Helper provides functions to ask the user for more information.
It is included in the default helper set, which you can get
by calling :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::

$dialog = $this->getHelperSet()->get('dialog');

All the methods inside the Dialog Helper have an
:class:`Symfony\\Component\\Console\\Output\\OutputInterface` as first argument,
the question as second argument and the default value as last argument.

Asking the User for confirmation
--------------------------------

Suppose you want to confirm an action before actually executing it. Add
the following to your command::

// ...
if (!$dialog->askConfirmation(
$output,
'<question>Continue with this action?</question>',
false
)) {
return;
}

In this case, the user will be asked "Continue with this action", and will return
``true`` if the user answers with ``y`` or false in any other case. The third
argument to ``askConfirmation`` is the default value to return if the user doesn't
enter any input.

Asking the User for information
-------------------------------

You can also ask question with more than a simple yes/no answer. For instance,
if you want to know a bundle name, you can add this to your command::

// ...
$bundle = $dialog->ask(
$output,
'Please enter the name of the bundle',
'AcmeDemoBundle'
);

The user will be asked "Please enter the name of the bundle". They can type
some name which will be returned by the ``ask`` method. If they leave it empty
the default value (``AcmeDemoBundle`` here) is returned.

Validating the answer
---------------------

You can even validate the answer. For instance, in our last example we asked
for the bundle name. Following the Symfony2 naming conventions, it should
be suffixed with ``Bundle``. We can validate that by using the
:method:`Symfony\\Component\\Console\\Helper\\DialogHelper::askAndValidate`
method::

// ...
$bundle = $dialog->askAndValidate(
$output,
'Please enter the name of the bundle',
function ($answer) {
if ('Bundle' !== substr($answer, -6)) {
throw new \RunTimeException(
'The name of the bundle should be suffixed with \'Bundle\''
);
}
},
false,
'AcmeDemoBundle'
);

This methods has 2 new arguments, the full signature is::

askAndValidate(
OutputInterface $output,
string|array $question,
callback $validator,
integer $attempts = false,
string $default = null
)

The ``$validator`` is a callback which handles the validation. It should
throw an exception if there is something wrong. The exception message is displayed
in the console, so it is a good practice to put some usefull information
in it.

You can set the max number of times to ask in the ``$attempts`` argument.
If we reach this max number it will use the default value, which is given
in the last argument. Using ``false`` means the amount of attempts is infinite.
The user will be asked as long as he provides an invalid answer and will only
be able to proceed if his input is valid.
52 changes: 52 additions & 0 deletionscomponents/console/helpers/formatterhelper.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
.. index::
single: Console Helpers; Formatter Helper

Formatter Helper
================

The Formatter helpers provides functions to format the output with colors.
You can do more advanced things with this helper than the things in
:ref:`components-console-coloring`.

The Formatter Helper is included in the default helper set, which you can
get by calling
:method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::

$formatter = $this->getHelperSet()->get('formatter');

The methods return a string which in most cases you want to write
that data to the console with
:method:`Symfony\\Component\\Console\\Output\\Output::writeln`.

Print messages in a section
---------------------------

Symfony uses a defined style when printing to the command line.
It prints the section in color and with brackets around and the
actual message behind this section indication.

To reproduce this style, you can use the
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatSection`::

$formattedLine = $formatter->formatSection('SomeCommand', 'Some output from within the SomeCommand');
$output->writeln($formattedLine);

Print messages in a block
-------------------------

Sometimes you want to be able to print a whole block of text with a background
color. Symfony uses this when printing error messages.

If you print your error message on more than one line manually, you will
notice that the background is only as long as each individual line. Use the
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
togenerate a block output::

$errorMessages = array('Error!', 'Something went wrong');
$formattedBlock = $formatter->formatBlock($errorMessages, 'error');

As you can see, passing an array of messages to the
:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
method creates the desired output. If you pass ``true`` as third parameter, the
block will be formatted with more padding (one blank line above and below the
messages and 2 spaces on the left and right).
16 changes: 16 additions & 0 deletionscomponents/console/helpers/index.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
.. index::
single: Console; Console Helpers

The Console Helpers
===================

.. toctree::
:hidden:

dialoghelper
formatterhelper

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

.. include:: map.rst.inc
2 changes: 2 additions & 0 deletionscomponents/console/helpers/map.rst.inc
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
* :doc:`/components/console/helpers/dialoghelper`
* :doc:`/components/console/helpers/formatterhelper`
2 changes: 2 additions & 0 deletionscomponents/console/index.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -7,3 +7,5 @@ Console
introduction
usage
single_command_tool

helpers/index
36 changes: 3 additions & 33 deletionscomponents/console/introduction.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -108,6 +108,8 @@ This prints::

HELLO FABIEN

.. _components-console-coloring:

Coloring the Output
~~~~~~~~~~~~~~~~~~~

Expand DownExpand Up@@ -255,38 +257,6 @@ You can combine VALUE_IS_ARRAY with VALUE_REQUIRED or VALUE_OPTIONAL like this:
1
);

Asking the User for Information
-------------------------------

When creating commands, you have the ability to collect more information
from the user by asking him/her questions. For example, suppose you want
to confirm an action before actually executing it. Add the following to your
command::

$dialog = $this->getHelperSet()->get('dialog');
if (!$dialog->askConfirmation(
$output,
'<question>Continue with this action?</question>',
false
)) {
return;
}

In this case, the user will be asked "Continue with this action", and unless
they answer with ``y``, the task will stop running. The third argument to
``askConfirmation`` is the default value to return if the user doesn't enter
any input.

You can also ask questions with more than a simple yes/no answer. For example,
if you needed to know the name of something, you might do the following::

$dialog = $this->getHelperSet()->get('dialog');
$name = $dialog->ask(
$output,
'Please enter the name of the widget',
'foo'
);

Testing Commands
----------------

Expand DownExpand Up@@ -407,4 +377,4 @@ Learn More!
* :doc:`/components/console/usage`
* :doc:`/components/console/single_command_tool`

.. _Packagist: https://packagist.org/packages/symfony/console
.. _Packagist: https://packagist.org/packages/symfony/console
1 change: 1 addition & 0 deletionscomponents/map.rst.inc
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -14,6 +14,7 @@
* :doc:`/components/console/introduction`
* :doc:`/components/console/usage`
* :doc:`/components/console/single_command_tool`
* :doc:`/components/console/helpers/index`

* **CSS Selector**

Expand Down
[8]ページ先頭
©2009-2025 Movatter.jp