[cookbook][console] Filling out the console cookbook article

Author: weaverryan

cookbook/console.rst

@@ -1,20 +1,23 @@
 How to Create Console/Command-Line Commands
 ===========================================
 
-Symfony2 ships with a console component. The framework offers a simple convention
-that allows you to register your own console commands for any recurring task,
-cronjobs, imports or other batch-jobs.
+Symfony2 ships with a console component, which allows you to create command-line
+tasks inside a rich and powerful framework. Your console commands can be used
+for any recurring task, such as cronjobs, imports or other batch jobs.
 
-To make the console commands available automatically with Symfony2 you have
-to create a ``Command`` directory inside your bundle and create a php file
-suffixed with ``Command.php`` for each task that you want to provide. If
-we want to to extend the HelloBundle to greet us from the command line as
-well we get this simple block of necessary code:
+Creating a Basic Command
+------------------------
 
-.. code-block: php
+To make the console commands available automatically with Symfony2, create
+a ``Command`` directory inside your bundle and create a php file suffixed
+with ``Command.php`` for each task that you want to provide. For example,
+if you want to extend the ``AcmeDemoBundle`` (available in the Symfony Standard
+Edition) to greet us from the command line, create ``GreetCommand.php`` and
+add the following to it:
 
-    <?php
-    // lib/Acme/DemoBundle/Command/GreetCommand.php
+.. code-block:: php
+
+    // src/Acme/DemoBundle/Command/GreetCommand.php
     namespace Acme\DemoBundle\Command;
 
     use Symfony\Bundle\FrameworkBundle\Command\Command;
@@ -31,54 +34,148 @@ well we get this simple block of necessary code:
                 ->setName('demo:greet')
                 ->setDescription('Greet someone')
                 ->addArgument('name', InputArgument::OPTIONAL, 'Who do you want to greet?')
+                ->addOption('yell', null, InputOption::VALUE_NONE, 'If set, the task will yell in uppercase letters')
             ;
         }
 
         protected function execute(InputInterface $input, OutputInterface $output)
         {
             $name = $input->getArgument('name');
             if ($name) {
-                $output->write('Hello ' . $name);
+                $text = 'Hello ' . $name;
             } else {
-                $output->write('Hello!');
+                $text = 'Hello';
+            }
+
+            if ($input->getOption('yell')) {
+                $text = strtoupper($text);
             }
+
+            $output->writeln($text);
         }
     }
 
-We can now test the greeting by calling:
+Test the new console command by running the following
 
-.. code-block:
+.. code-block:: bash
 
-    $> ./app/console demo:greet Fabien
-    Hello Fabien!
+    $ php app/console demo:greet Fabien
 
-Advanced Usage
---------------
+This will print the following to the command line::
 
-Using the Dependency Injection Container
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Hello Fabien
 
-Using the Symfony\Bundle\FrameworkBundle\Command\Command as base class we
-also have access to the dependency injection container. As an example we
-could easily extend our task to be translatable:
+You can also use the ``--yell`` option to make everything uppercase:
 
-.. code-block: php
+.. code-block:: bash
 
-    <?php
-    // lib/Acme/DemoBundle/Command/GreetCommand.php
+    $ php app/console demo:greet Fabien --yell
 
-    // ...
-    class GreetCommand extends Command
+This prints::
+
+    HELLO FABIEN
+
+Command Arguments
+~~~~~~~~~~~~~~~~~
+
+The most interesting part of the commands are the arguments and options that
+you can make available. Arguments are the strings - separated by spaces - that
+come after the command name itself. They are ordered, and can be optional
+or required. For example, add an optional ``last_name`` argument to the command
+and make the ``name`` argument required:
+
+.. code-block:: php
+
+    $this
+        // ...
+        ->addArgument('name', InputArgument::REQUIRED, 'Who do you want to greet?')
+        ->addArgument('last_name', InputArgument::OPTIONAL, 'Your last name?')
+        // ...
+
+You now have access to a ``last_name`` argument in your command:
+
+.. code-block:: php
+
+    if ($lastName = $input->getArgument('last_name')) {
+        $text .= ' ' . $lastName;
+    }
+
+The command can now be used in either of the following ways:
+
+.. code-block:: bash
+
+    $ php app/console demo:greet Fabien
+    $ php app/console demo:greet Fabien Potencier
+
+Command Options
+---------------
+
+Unlike arguments, options are not ordered (meaning you can specify them in
+any order) and are specified with two dashes (e.g. ``--yell``). Options are
+*always* optional, and can be setup to accept a value (e.g. ``dir=src``)
+or simply as a boolean flag without a value (e.g. ``yell``).
+
+.. tip::
+
+    It's also possible to make an option *optionally* accept a value (so
+    that ``--yell`` or ``yell=loud`` work). Options can also be configured
+    to accept an array of values.
+
+For example, add a new option to the command that can be used to specify
+how many times in a row the message should be printed:
+
+.. code-block:: php
+
+    $this
+        // ...
+        ->addOption('iterations', null, InputOption::VALUE_REQUIRED, 'How many times should the message be printed?', 1)
+
+Next, use this in the command to print the message multiple times:
+
+.. code-block:: php
+
+    for ($i = 0; $i < $input->getOption('iterations'); $i++) {
+        $output->writeln($text);
+    }
+
+Now, when you run the task, you can optionally specify a ``--iterations``
+flag:
+
+.. code-block:: bash
+
+    $ php app/console demo:greet Fabien
+
+    $ php app/console demo:greet Fabien --iterations=5
+
+The first example will only print once, since ``iterations`` is empty and
+defaults to ``1`` (the last argument of ``addOption``). The second example
+will print five times.
+
+Recall that options don't care about their order. So, either of the following
+will work:
+
+.. code-block:: bash
+
+    $ php app/console demo:greet Fabien --iterations=5 --yell
+    $ php app/console demo:greet Fabien --yell --iterations=5
+
+Advanced Usage with the Service Container
+-----------------------------------------
+
+By Using the :class:`Symfony\\Bundle\\FrameworkBundle\\Command\\Command`
+as the base class for the command, you have access to the service container.
+In other words, you have access to use any service configured to work inside
+Symfony. For example, you could easily extend the task to be translatable:
+
+.. code-block:: php
+
+    protected function execute(InputInterface $input, OutputInterface $output)
     {
-        //...
-        protected function execute(InputInterface $input, OutputInterface $output)
-        {
-            $name = $input->getArgument('name');
-            $translator = $this->container->get('translator');
-            if ($name) {
-                $output->write($translator->trans('Hello %name%!', array('%name%' => $name)));
-            } else {
-                $output->write($translator->trans('Hello!'));
-            }
+        $name = $input->getArgument('name');
+        $translator = $this->container->get('translator');
+        if ($name) {
+            $output->writeln($translator->trans('Hello %name%!', array('%name%' => $name)));
+        } else {
+            $output->writeln($translator->trans('Hello!'));
         }
     }