console.rst

How to Create Console/Command-Line Commands

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.

Creating a Basic Command

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:

// src/Acme/DemoBundle/Command/GreetCommand.php
namespace Acme\DemoBundle\Command;

use Symfony\Bundle\FrameworkBundle\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;

class GreetCommand extends Command
{
    protected function configure()
    {
        $this
            ->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) {
            $text = 'Hello ' . $name;
        } else {
            $text = 'Hello';
        }

        if ($input->getOption('yell')) {
            $text = strtoupper($text);
        }

        $output->writeln($text);
    }
}

Test the new console command by running the following

$ php app/console demo:greet Fabien

This will print the following to the command line:

Hello Fabien

You can also use the --yell option to make everything uppercase:

$ php app/console demo:greet Fabien --yell

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:

$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:

if ($lastName = $input->getArgument('last_name')) {
    $text .= ' ' . $lastName;
}

The command can now be used in either of the following ways:

$ 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:

$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:

for ($i = 0; $i < $input->getOption('iterations'); $i++) {
    $output->writeln($text);
}

Now, when you run the task, you can optionally specify a --iterations flag:

$ 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:

$ 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:

protected function execute(InputInterface $input, OutputInterface $output)
{
    $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!'));
    }
}