diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst new file mode 100644 index 00000000000..647461f00d6 --- /dev/null +++ b/components/console/helpers/dialoghelper.rst @@ -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, + 'Continue with this action?', + 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. \ No newline at end of file diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst new file mode 100644 index 00000000000..a52debce80f --- /dev/null +++ b/components/console/helpers/formatterhelper.rst @@ -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). \ No newline at end of file diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst new file mode 100644 index 00000000000..c11b6e1a994 --- /dev/null +++ b/components/console/helpers/index.rst @@ -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 diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc new file mode 100644 index 00000000000..d324d8c2aeb --- /dev/null +++ b/components/console/helpers/map.rst.inc @@ -0,0 +1,2 @@ +* :doc:`/components/console/helpers/dialoghelper` +* :doc:`/components/console/helpers/formatterhelper` diff --git a/components/console/index.rst b/components/console/index.rst index b3e3cf95d97..4d0a12e4d70 100644 --- a/components/console/index.rst +++ b/components/console/index.rst @@ -7,3 +7,5 @@ Console introduction usage single_command_tool + + helpers/index diff --git a/components/console/introduction.rst b/components/console/introduction.rst index a7412879a60..d614c11f383 100755 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -108,6 +108,8 @@ This prints:: HELLO FABIEN +.. _components-console-coloring: + Coloring the Output ~~~~~~~~~~~~~~~~~~~ @@ -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, - 'Continue with this action?', - 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 ---------------- @@ -407,4 +377,4 @@ Learn More! * :doc:`/components/console/usage` * :doc:`/components/console/single_command_tool` -.. _Packagist: https://packagist.org/packages/symfony/console \ No newline at end of file +.. _Packagist: https://packagist.org/packages/symfony/console diff --git a/components/map.rst.inc b/components/map.rst.inc index 97cb03134c1..0529c6d4e16 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -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**