How to create a task

As any web application, your project has repetitive maintenance tasks, database operations, or other console scripts running on a regular basis.

Symfony 1.1 extends symfony 1.0 pake tasks to create a powerful and uniform command line utility for your projects, fully integrated with the symfony Command Line Interface (CLI).

• Accessibility: Any task can be run with the help parameter prepended, to get the syntax, a description, available options, and more. Anybody will be able to run your tasks.
• Usability: Running the symfony CLI will give you the task list, and even a non developer will be able to learn easily how to run one.
• Uniformity: By explicitly describing every options and parameters, symfony CLI will parse them so you can forget about the troublesome repetitive task of parsing $argv. It will automatically warn the user of wrong syntax or missing parameters.
• Environment: The context is fully controlled, thanks to the new ProjectConfiguration and ApplicationConfiguration classes. You won't worry anymore about hard-coded environment or debug settings.
• Readability: Anyone opening the source code will get great description of the expected input and the goals of the task. Maintenance time took to understand and debug this code will be greatly reduced.

Let's write our first task

Open your symfony 1.1 project directory and type:

$ php symfony generate:task doNothing

It will bootstrap an empty task in lib/task/doNothingTask.class.php. Let's tune it a bit.

class doNothingTask extends sfBaseTask
{
  protected function configure()
  {
    $this->namespace        = 'project';
    $this->name             = 'do-nothing';
    $this->briefDescription = 'Does strictly nothing';
 
    $this->detailedDescription = <<<EOF
This task is completely useless, and should be run as often as possible.
EOF;
  }
 
  protected function execute($arguments = array(), $options = array())
  {
    $this->logSection('do-nothing', 'I did nothing successfully!');
  }
}

This task for sure does not much, but demonstrates the first basic concepts.:

• The configure() method describes the task. Invocation name, scope, syntax, help, options and arguments.
• The execute() method is the one who does all the job actually, and will be called when the task is run.
• The logSection() method can be used to print messages on the console output.

You can play around a bit with it:

$ php symfony help project:do-nothing
$ php symfony project:do-nothing

Some command line interaction

Arguments and options are the way to give parameters to a task.

$ php symfony project:hello-world --name="Romain"

Here we're running the project:hello-world task with the name option set to Romain

$ php symfony project:hello-world Hi

Now, we run the same task with the first argument set to Hi.

Options and arguments can have default values, be optional or required and embed their purpose to be displayed in task syntax.

Let's write our project:hello-world task:

class doHelloWorldTask extends sfBaseTask
{
  protected function configure()
  {
    $this->addArgument('verb', sfCommandArgument::OPTIONAL, 'Customize the verb used to say hello', 'hello');
    $this->addOption('name', null, sfCommandOption::PARAMETER_OPTIONAL, 'Customize the person to say hello to', 'world');
 
    $this->namespace        = 'project';
    $this->name             = 'hello-world';
    $this->briefDescription = 'Spread the (hello) world';
 
    $this->detailedDescription = <<<EOF
Runs an evolved hello world display, with customisable name and word.
EOF;
  }
 
  protected function execute($arguments = array(), $options = array())
  {
    $this->logSection('do', ucfirst($arguments['verb']).' '.ucfirst($options['name']));
  }
}

Now check out how symfony helps the lost user about how to use our new task:

$ php symfony project:hello-world invalid arguments given
$ php symfony help project:hello-world

And play a bit with the task:

$ php symfony project:hello-world
$ php symfony project:hello-world --name="romain"
$ php symfony project:hello-world --name=romain hi
$ php symfony project:hello-world hi --name=romain

Some other handy features

• Do you need the database layer?

  protected function execute($arguments = array(), $options = array())
  {
    $databaseManager = new sfDatabaseManager($this->configuration);
   
    // ...
  }

• Run another task within a task?

  $myOtherTask = new myOtherTask($this->dispatcher, $this->formatter);
  $myOtherTask->run($arguments = array('foo' => 'bar'), $options = array('far' => 'boo'));

• Need to let the user choose the environment, while providing a default one?

  Just add the env option in the ::configure() method and symfony will use its value as the environemnt.

  $this->addOption('env', null, sfCommandOption::PARAMETER_OPTIONAL, 'Changes the environment this task is run in', 'prod');

What do you think? Isn't this some cherry on the cake, or for instance, some jazzy chorus over the symfony?