[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!'));
  }
  }