From 3e133d30d2f94e1b99629463767ecf4d7f7f5927 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 15 Dec 2015 18:04:31 +0100 Subject: [PATCH 1/5] Documented the Symfony Console Styles --- cookbook/console/index.rst | 1 + cookbook/console/style.rst | 363 +++++++++++++++++++++++++++++++++++++ cookbook/map.rst.inc | 1 + 3 files changed, 365 insertions(+) create mode 100644 cookbook/console/style.rst diff --git a/cookbook/console/index.rst b/cookbook/console/index.rst index c3628beb4f7..a063afcf920 100644 --- a/cookbook/console/index.rst +++ b/cookbook/console/index.rst @@ -6,6 +6,7 @@ Console console_command usage + style command_in_controller sending_emails logging diff --git a/cookbook/console/style.rst b/cookbook/console/style.rst new file mode 100644 index 00000000000..af18787db10 --- /dev/null +++ b/cookbook/console/style.rst @@ -0,0 +1,363 @@ +.. index:: + single: Console; Style commands + +How to Style a Console Command +============================== + +One of the most boring tasks when creating console commands is to deal with the +styling of the command's input and output. Displaying titles and tables or asking +questions to the user involves a lot of repetitive code. + +Consider for example the code used to display the title of the following command:: + + // src/AppBundle/Command/GreetCommand.php + namespace AppBundle\Command; + + use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand; + use Symfony\Component\Console\Input\InputInterface; + use Symfony\Component\Console\Output\OutputInterface; + + class GreetCommand extends ContainerAwareCommand + { + // ... + + protected function execute(InputInterface $input, OutputInterface $output) + { + $output->writeln('Lorem Ipsum Dolor Sit Amet'); + $output->writeln('=========================='); + $output->writeln(''); + + // ... + } + } + +Displaying a simple title requires three lines of code, to change the font color, +underline the contents and leave an additional blank line after the title. Dealing +with styles is required for well-designed commands, but it complicates their code +unnecessarily. + +In order to reduce that boilerplate code, Symfony commands can optionally use the +**Symfony Style Guide**. These styles are implemented as a set of helper methods +which allow to create *semantic* commands and forget about their styling. + +Basic Usage +----------- + +In your command, instantiate the :class:`Symfony\\Component\\Console\\Helper\\SymfonyStyle` +class and pass the ``$input`` and ``$output`` variables as its arguments. Then, +you can start using any of its helpers, such as ``title()``, which displays the +title of the command:: + + // src/AppBundle/Command/GreetCommand.php + namespace AppBundle\Command; + + use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand; + use Symfony\Component\Console\Helper\SymfonyStyle; + use Symfony\Component\Console\Input\InputInterface; + use Symfony\Component\Console\Output\OutputInterface; + + class GreetCommand extends ContainerAwareCommand + { + // ... + + protected function execute(InputInterface $input, OutputInterface $output) + { + $io = new SymfonyStyle($input, $output); + $io->title('Lorem Ipsum Dolor Sit Amet'); + + // ... + } + } + +.. tip:: + + You can use any name for the variable that stores the Symfony styles, but + it's recommended to name it ``$io`` because it's concise and conveys the + notion that it interacts both with the input and the output of the command. + +Helper Methods +-------------- + +The :class:`Symfony\\Component\\Console\\Helper\\SymfonyStyle` class defines 18 +helper methods that cover the most common interactions performed by console commands. + +Common Output Elements +~~~~~~~~~~~~~~~~~~~~~~ + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::title` + It displays the given string as the command title. This method is meant to + be used only once in a given command, but nothing prevents you to use it + repeatedly:: + + $io->title('Lorem ipsum dolor sit amet'); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::section` + It displays the given string as the title of some command section. This is + only needed in complex commands which want to better separate their contents:: + + $io->section('Adding a User'); + + // ... + + $io->section('Generating the Password'); + + // ... + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::text` + It displays the given string or array of strings as regular text. This is + useful to render help messages and instructions for the user running the + command:: + + // use simple strings for short messages + $io->text('Lorem ipsum dolor sit amet'); + + // ... + + // consider using arrays when displaying long messages + $io->text(array( + 'Lorem ipsum dolor sit amet', + 'Consectetur adipiscing elit', + 'Aenean sit amet arcu vitae sem faucibus porta' + )); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::listing` + It displays an unordered list of elements passed as an array:: + + $io->listing(array( + 'Element #1 Lorem ipsum dolor sit amet', + 'Element #2 Lorem ipsum dolor sit amet', + 'Element #3 Lorem ipsum dolor sit amet', + )); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::table` + It displays the given array of headers and rows as a compact table:: + + $io->table( + array('Header 1', 'Header 2'), + array( + array('Cell 1-1', 'Cell 1-2'), + array('Cell 2-1', 'Cell 2-2'), + array('Cell 3-1', 'Cell 3-2'), + ) + ); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::note` + It displays the given string or array of strings as a highlighted admonition. + Use this helper sparingly to avoid cluttering command's output:: + + // use simple strings for short notes + $io->note('Lorem ipsum dolor sit amet'); + + // ... + + // consider using arrays when displaying long notes + $io->note(array( + 'Lorem ipsum dolor sit amet', + 'Consectetur adipiscing elit', + 'Aenean sit amet arcu vitae sem faucibus porta' + )); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::caution` + Similar to the ``note()`` helper, but the contents are more prominently + highlighted. The resulting contents resemble an error message, so you should + avoid using this helper unless strictly necessary:: + + // use simple strings for short caution message + $io->note('Lorem ipsum dolor sit amet'); + + // ... + + // consider using arrays when displaying long caution messages + $io->note(array( + 'Lorem ipsum dolor sit amet', + 'Consectetur adipiscing elit', + 'Aenean sit amet arcu vitae sem faucibus porta' + )); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::newLine` + It displays a blank line in the command output. Although it may seem useful, + most of the times you won't need it at all. The reason is that every helper + already adds their own blank lines, so you don't have to care about the + vertical spacing:: + + // outputs a single blank line + $io->newLine(); + + // outputs three consecutive blank lines + $io->newLine(3); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::progressStart` + It displays a progress bar with a number of steps equal to the argument passed + to the method (don't pass any value if the length of the progress bar is + unknown):: + + // display a progress bar of unknown length + $io->progressStart(); + + // display a 100-step length progress bar + $io->progressStart(100); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::progressAdvance` + It makes the progress bar advance the given number of steps (or ``1`` step + if no argument is passed):: + + // advanced the progress bar 1 step + $io->progressStart(); + + // advanced the progress bar 10 steps + $io->progressStart(10); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::progressFinish` + It finishes the progress bar (filling up all the remaining steps when its + length is known):: + + $io->progressFinish(10); + +Asking for User's Input +~~~~~~~~~~~~~~~~~~~~~~~ + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::ask` + It asks the user to provide some value:: + + $io->ask('What is your name?'); + + You can pass the default value as the second argument so the user can simply + hit the key to select that value:: + + $io->ask('Where are you from?', 'United States'); + + In case you need to validate the given value, pass a callback validator as + the third argument: + + $io->ask('Number of workers to start', 1, function ($number) { + if (!is_integer($number)) { + throw new \RuntimeException('You must type an integer.'); + } + + return $number; + }); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::askHidden` + It's very similar to the ``ask()`` method but the user's input will be hidden + and it cannot define a default value. Use it when asking for sensitive information:: + + $io->ask('What is your password?'); + + $io->ask('What is your password?', function ($password) { + if (empty($password)) { + throw new \RuntimeException('Password cannot be empty.'); + } + + return $password; + }); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::confirm` + It asks a Yes/No question to the user and it only returns ``true`` or ``false``:: + + $io->('Restart the web server?'); + + You can pass the default value as the second argument so the user can simply + hit the key to select that value:: + + $io->('Restart the web server?', true); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::choice` + It asks a question whose answer is constrained to the given list of valid + answers:: + + $io->('Which queue do you want to analyze?', array('queue1', 'queue2', 'queue3')); + + You can pass the default value as the third argument so the user can simply + hit the key to select that value:: + + $io->('Which queue do you want to analyze?', array('queue1', 'queue2', 'queue3'), 'queue1'); + +Displaying the Result of the Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::success` + It displays the given string or array of strings highlighted as a successful + message (with a green background and the ``[OK]`` label). It's meant to be + used once to display the final result of executing the given command, but you + can use it repeatedly during the execution of the command:: + + // use simple strings for short success messages + $io->success('Lorem ipsum dolor sit amet'); + + // ... + + // consider using arrays when displaying long success messages + $io->success(array( + 'Lorem ipsum dolor sit amet', + 'Consectetur adipiscing elit', + )); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::warning` + It displays the given string or array of strings highlighted as a warning + message (with a read background and the ``[WARNING]`` label). It's meant to be + used once to display the final result of executing the given command, but you + can use it repeatedly during the execution of the command:: + + // use simple strings for short warning messages + $io->warning('Lorem ipsum dolor sit amet'); + + // ... + + // consider using arrays when displaying long warning messages + $io->warning(array( + 'Lorem ipsum dolor sit amet', + 'Consectetur adipiscing elit', + )); + +:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::error` + It displays the given string or array of strings highlighted as an error + message (with a read background and the ``[ERROR]`` label). It's meant to be + used once to display the final result of executing the given command, but you + can use it repeatedly during the execution of the command:: + + // use simple strings for short error messages + $io->error('Lorem ipsum dolor sit amet'); + + // ... + + // consider using arrays when displaying long error messages + $io->error(array( + 'Lorem ipsum dolor sit amet', + 'Consectetur adipiscing elit', + )); + +Defining your Own Styles +------------------------ + +If you don't like the design of the commands that use the Symfony Style, you can +define your own set of console styles. Just create a class that implements the +:class:`Symfony\Component\Console\Style\StyleInterface`:: + + namespace AppBundle\Console; + + use Symfony\Component\Console\Style\StyleInterface; + + class CustomStyle + { + // implement the methods of the interface... + } + +Then, instantiate this custom class instead of the default ``SymfonyStyle`` in +your commands. Thanks to the ``StyleInterface`` you won't need to change the code +of your commands to change their appearance:: + + namespace AppBundle\Console; + + use AppBundle\Console\CustomStyle; + use Symfony\Component\Console\Style\SymfonyStyle; + + public function execute() + { + // Before + // $io = new SymfonyStyle(); + + // After + // $io = new CustomStyle(); + + // ... + } diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 8049b6b320d..791b9bccdb8 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -44,6 +44,7 @@ * :doc:`/cookbook/console/console_command` * :doc:`/cookbook/console/usage` + * :doc:`/cookbook/console/style` * :doc:`/cookbook/console/command_in_controller` * :doc:`/cookbook/console/sending_emails` * :doc:`/cookbook/console/logging` From 093a8159c70859a54cfba9b01bfb8795b920917e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 16 Dec 2015 08:48:56 +0100 Subject: [PATCH 2/5] Fixed issues mentioned by reviewers --- cookbook/console/style.rst | 58 ++++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 25 deletions(-) diff --git a/cookbook/console/style.rst b/cookbook/console/style.rst index af18787db10..45097dd6be6 100644 --- a/cookbook/console/style.rst +++ b/cookbook/console/style.rst @@ -43,7 +43,7 @@ which allow to create *semantic* commands and forget about their styling. Basic Usage ----------- -In your command, instantiate the :class:`Symfony\\Component\\Console\\Helper\\SymfonyStyle` +In your command, instantiate the :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle` class and pass the ``$input`` and ``$output`` variables as its arguments. Then, you can start using any of its helpers, such as ``title()``, which displays the title of the command:: @@ -78,7 +78,7 @@ title of the command:: Helper Methods -------------- -The :class:`Symfony\\Component\\Console\\Helper\\SymfonyStyle` class defines 18 +The :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle` class defines 18 helper methods that cover the most common interactions performed by console commands. Common Output Elements @@ -117,7 +117,7 @@ Common Output Elements $io->text(array( 'Lorem ipsum dolor sit amet', 'Consectetur adipiscing elit', - 'Aenean sit amet arcu vitae sem faucibus porta' + 'Aenean sit amet arcu vitae sem faucibus porta', )); :method:`Symfony\\Component\\Console\\Helper\\StyleInterface::listing` @@ -163,12 +163,12 @@ Common Output Elements avoid using this helper unless strictly necessary:: // use simple strings for short caution message - $io->note('Lorem ipsum dolor sit amet'); + $io->caution('Lorem ipsum dolor sit amet'); // ... // consider using arrays when displaying long caution messages - $io->note(array( + $io->caution(array( 'Lorem ipsum dolor sit amet', 'Consectetur adipiscing elit', 'Aenean sit amet arcu vitae sem faucibus porta' @@ -191,27 +191,27 @@ Common Output Elements to the method (don't pass any value if the length of the progress bar is unknown):: - // display a progress bar of unknown length + // displays a progress bar of unknown length $io->progressStart(); - // display a 100-step length progress bar + // displays a 100-step length progress bar $io->progressStart(100); :method:`Symfony\\Component\\Console\\Helper\\StyleInterface::progressAdvance` It makes the progress bar advance the given number of steps (or ``1`` step if no argument is passed):: - // advanced the progress bar 1 step - $io->progressStart(); + // advances the progress bar 1 step + $io->progressAdvance(); - // advanced the progress bar 10 steps - $io->progressStart(10); + // advances the progress bar 10 steps + $io->progressAdvance(10); :method:`Symfony\\Component\\Console\\Helper\\StyleInterface::progressFinish` It finishes the progress bar (filling up all the remaining steps when its length is known):: - $io->progressFinish(10); + $io->progressFinish(); Asking for User's Input ~~~~~~~~~~~~~~~~~~~~~~~ @@ -227,7 +227,7 @@ Asking for User's Input $io->ask('Where are you from?', 'United States'); In case you need to validate the given value, pass a callback validator as - the third argument: + the third argument:: $io->ask('Number of workers to start', 1, function ($number) { if (!is_integer($number)) { @@ -243,6 +243,7 @@ Asking for User's Input $io->ask('What is your password?'); + // validates the given answer $io->ask('What is your password?', function ($password) { if (empty($password)) { throw new \RuntimeException('Password cannot be empty.'); @@ -254,23 +255,23 @@ Asking for User's Input :method:`Symfony\\Component\\Console\\Helper\\StyleInterface::confirm` It asks a Yes/No question to the user and it only returns ``true`` or ``false``:: - $io->('Restart the web server?'); + $io->confirm('Restart the web server?'); You can pass the default value as the second argument so the user can simply hit the key to select that value:: - $io->('Restart the web server?', true); + $io->confirm('Restart the web server?', true); :method:`Symfony\\Component\\Console\\Helper\\StyleInterface::choice` It asks a question whose answer is constrained to the given list of valid answers:: - $io->('Which queue do you want to analyze?', array('queue1', 'queue2', 'queue3')); + $io->choice('Select the queue to analyze', array('queue1', 'queue2', 'queue3')); You can pass the default value as the third argument so the user can simply hit the key to select that value:: - $io->('Which queue do you want to analyze?', array('queue1', 'queue2', 'queue3'), 'queue1'); + $io->choice('Select the queue to analyze', array('queue1', 'queue2', 'queue3'), 'queue1'); Displaying the Result of the Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -331,13 +332,13 @@ Defining your Own Styles If you don't like the design of the commands that use the Symfony Style, you can define your own set of console styles. Just create a class that implements the -:class:`Symfony\Component\Console\Style\StyleInterface`:: +:class:`Symfony\\Component\\Console\\Style\\StyleInterface`:: namespace AppBundle\Console; use Symfony\Component\Console\Style\StyleInterface; - class CustomStyle + class CustomStyle implements StyleInterface { // implement the methods of the interface... } @@ -349,15 +350,22 @@ of your commands to change their appearance:: namespace AppBundle\Console; use AppBundle\Console\CustomStyle; + use Symfony\Component\Console\Input\InputInterface; + use Symfony\Component\Console\Output\OutputInterface; use Symfony\Component\Console\Style\SymfonyStyle; - public function execute() + class GreetCommand extends ContainerAwareCommand { - // Before - // $io = new SymfonyStyle(); + // ... - // After - // $io = new CustomStyle(); + public function execute(InputInterface $input, OutputInterface $output) + { + // Before + // $io = new SymfonyStyle($input, $output); - // ... + // After + $io = new CustomStyle($input, $output); + + // ... + } } From 1523ea7dc55f94aafe5b5f3be888501d6f51a38f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 18 Dec 2015 16:10:59 +0100 Subject: [PATCH 3/5] Another round of reviews --- cookbook/console/style.rst | 105 +++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 50 deletions(-) diff --git a/cookbook/console/style.rst b/cookbook/console/style.rst index 45097dd6be6..4bdbf735311 100644 --- a/cookbook/console/style.rst +++ b/cookbook/console/style.rst @@ -23,9 +23,11 @@ Consider for example the code used to display the title of the following command protected function execute(InputInterface $input, OutputInterface $output) { - $output->writeln('Lorem Ipsum Dolor Sit Amet'); - $output->writeln('=========================='); - $output->writeln(''); + $output->writeln(array( + 'Lorem Ipsum Dolor Sit Amet', + '==========================', + '', + )); // ... } @@ -52,7 +54,7 @@ title of the command:: namespace AppBundle\Command; use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand; - use Symfony\Component\Console\Helper\SymfonyStyle; + use Symfony\Component\Console\Style\SymfonyStyle; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Output\OutputInterface; @@ -69,29 +71,23 @@ title of the command:: } } -.. tip:: - - You can use any name for the variable that stores the Symfony styles, but - it's recommended to name it ``$io`` because it's concise and conveys the - notion that it interacts both with the input and the output of the command. - Helper Methods -------------- -The :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle` class defines 18 +The :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle` class defines some helper methods that cover the most common interactions performed by console commands. -Common Output Elements -~~~~~~~~~~~~~~~~~~~~~~ +Titling Methods +~~~~~~~~~~~~~~~ -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::title` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::title` It displays the given string as the command title. This method is meant to be used only once in a given command, but nothing prevents you to use it repeatedly:: $io->title('Lorem ipsum dolor sit amet'); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::section` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::section` It displays the given string as the title of some command section. This is only needed in complex commands which want to better separate their contents:: @@ -103,7 +99,10 @@ Common Output Elements // ... -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::text` +Content Methods +~~~~~~~~~~~~~~~ + +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::text` It displays the given string or array of strings as regular text. This is useful to render help messages and instructions for the user running the command:: @@ -120,7 +119,7 @@ Common Output Elements 'Aenean sit amet arcu vitae sem faucibus porta', )); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::listing` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::listing` It displays an unordered list of elements passed as an array:: $io->listing(array( @@ -129,7 +128,7 @@ Common Output Elements 'Element #3 Lorem ipsum dolor sit amet', )); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::table` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::table` It displays the given array of headers and rows as a compact table:: $io->table( @@ -141,7 +140,22 @@ Common Output Elements ) ); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::note` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::newLine` + It displays a blank line in the command output. Although it may seem useful, + most of the times you won't need it at all. The reason is that every helper + already adds their own blank lines, so you don't have to care about the + vertical spacing:: + + // outputs a single blank line + $io->newLine(); + + // outputs three consecutive blank lines + $io->newLine(3); + +Admonition Methods +~~~~~~~~~~~~~~~~~~ + +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::note` It displays the given string or array of strings as a highlighted admonition. Use this helper sparingly to avoid cluttering command's output:: @@ -154,10 +168,10 @@ Common Output Elements $io->note(array( 'Lorem ipsum dolor sit amet', 'Consectetur adipiscing elit', - 'Aenean sit amet arcu vitae sem faucibus porta' + 'Aenean sit amet arcu vitae sem faucibus porta', )); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::caution` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::caution` Similar to the ``note()`` helper, but the contents are more prominently highlighted. The resulting contents resemble an error message, so you should avoid using this helper unless strictly necessary:: @@ -171,22 +185,13 @@ Common Output Elements $io->caution(array( 'Lorem ipsum dolor sit amet', 'Consectetur adipiscing elit', - 'Aenean sit amet arcu vitae sem faucibus porta' + 'Aenean sit amet arcu vitae sem faucibus porta', )); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::newLine` - It displays a blank line in the command output. Although it may seem useful, - most of the times you won't need it at all. The reason is that every helper - already adds their own blank lines, so you don't have to care about the - vertical spacing:: - - // outputs a single blank line - $io->newLine(); - - // outputs three consecutive blank lines - $io->newLine(3); +Progress Bar Methods +~~~~~~~~~~~~~~~~~~~~ -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::progressStart` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::progressStart` It displays a progress bar with a number of steps equal to the argument passed to the method (don't pass any value if the length of the progress bar is unknown):: @@ -197,7 +202,7 @@ Common Output Elements // displays a 100-step length progress bar $io->progressStart(100); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::progressAdvance` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::progressAdvance` It makes the progress bar advance the given number of steps (or ``1`` step if no argument is passed):: @@ -207,16 +212,16 @@ Common Output Elements // advances the progress bar 10 steps $io->progressAdvance(10); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::progressFinish` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::progressFinish` It finishes the progress bar (filling up all the remaining steps when its length is known):: $io->progressFinish(); -Asking for User's Input -~~~~~~~~~~~~~~~~~~~~~~~ +User Input Methods +~~~~~~~~~~~~~~~~~~ -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::ask` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::ask` It asks the user to provide some value:: $io->ask('What is your name?'); @@ -237,14 +242,14 @@ Asking for User's Input return $number; }); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::askHidden` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::askHidden` It's very similar to the ``ask()`` method but the user's input will be hidden and it cannot define a default value. Use it when asking for sensitive information:: - $io->ask('What is your password?'); + $io->askHidden('What is your password?'); // validates the given answer - $io->ask('What is your password?', function ($password) { + $io->askHidden('What is your password?', function ($password) { if (empty($password)) { throw new \RuntimeException('Password cannot be empty.'); } @@ -252,7 +257,7 @@ Asking for User's Input return $password; }); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::confirm` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::confirm` It asks a Yes/No question to the user and it only returns ``true`` or ``false``:: $io->confirm('Restart the web server?'); @@ -262,7 +267,7 @@ Asking for User's Input $io->confirm('Restart the web server?', true); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::choice` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::choice` It asks a question whose answer is constrained to the given list of valid answers:: @@ -273,10 +278,10 @@ Asking for User's Input $io->choice('Select the queue to analyze', array('queue1', 'queue2', 'queue3'), 'queue1'); -Displaying the Result of the Command -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Result Methods +~~~~~~~~~~~~~~ -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::success` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::success` It displays the given string or array of strings highlighted as a successful message (with a green background and the ``[OK]`` label). It's meant to be used once to display the final result of executing the given command, but you @@ -293,7 +298,7 @@ Displaying the Result of the Command 'Consectetur adipiscing elit', )); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::warning` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::warning` It displays the given string or array of strings highlighted as a warning message (with a read background and the ``[WARNING]`` label). It's meant to be used once to display the final result of executing the given command, but you @@ -310,7 +315,7 @@ Displaying the Result of the Command 'Consectetur adipiscing elit', )); -:method:`Symfony\\Component\\Console\\Helper\\StyleInterface::error` +:method:`Symfony\\Component\\Console\\Style\\StyleInterface::error` It displays the given string or array of strings highlighted as an error message (with a read background and the ``[ERROR]`` label). It's meant to be used once to display the final result of executing the given command, but you @@ -340,7 +345,7 @@ define your own set of console styles. Just create a class that implements the class CustomStyle implements StyleInterface { - // implement the methods of the interface... + // ...implement the methods of the interface } Then, instantiate this custom class instead of the default ``SymfonyStyle`` in From 9528c3cf7d22f77d5ea83002832e58d8f51fb679 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 21 Dec 2015 10:29:01 +0100 Subject: [PATCH 4/5] Minor change for consistency --- cookbook/console/style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/console/style.rst b/cookbook/console/style.rst index 4bdbf735311..7f24ca1f088 100644 --- a/cookbook/console/style.rst +++ b/cookbook/console/style.rst @@ -363,7 +363,7 @@ of your commands to change their appearance:: { // ... - public function execute(InputInterface $input, OutputInterface $output) + protected function execute(InputInterface $input, OutputInterface $output) { // Before // $io = new SymfonyStyle($input, $output); From 02356a13fc1f15e56cb51a4264ff17ce489264cb Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 28 Dec 2015 12:11:11 +0100 Subject: [PATCH 5/5] Added the "versionadded" directive --- cookbook/console/style.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cookbook/console/style.rst b/cookbook/console/style.rst index 7f24ca1f088..3ddcf85a45a 100644 --- a/cookbook/console/style.rst +++ b/cookbook/console/style.rst @@ -4,6 +4,9 @@ How to Style a Console Command ============================== +.. versionadded:: 2.7 + Symfony Styles for console commands were introduced in Symfony 2.7. + One of the most boring tasks when creating console commands is to deal with the styling of the command's input and output. Displaying titles and tables or asking questions to the user involves a lot of repetitive code.