The symfony Cookbook

Comme la plupart des applications, votre projet peut comporter des travaux de maintenance, des opérations de base de données ou d'autres scripts lancés régulièrement en ligne de commande.

Symfony 1.1 enrichie les tâches pake de la version 1.0 créant ainsi un utilitaire de commande uniforme et puissant, complètement intégré au CLI (interface en ligne de commande) de symfony.

• Accessibilité: Chaque tâche à lancer peut être préfixé du paramètre help, pour afficher la syntaxe, la description, les options disponibles et d'autres informations. Tout le monde pourra ainsi profiter de vos tâches.
• Utilisabilité: En lançant l'utilitaire de commande symfony, la liste des tâches est présenté. Ainsi, même un non dévelopeur pourra apprendre facilement comment en exécuter une.
• Uniformité: En décrivant explicitement chaque options et paramètres, l'utilitaire de commande symfony les traitera pour vous, vous évitant ainsi l'analyse répétitive et souvent problématique de $argv. Il avertira automatiquement l'utilisateur si la syntaxe est incorrect ou si des paramètres sont manquants.
• Environnement: Grâce aux nouvelles classes ProjectConfiguration et ApplicationConfiguration, Le contexte en entièrement maîtrisé. Fini les soucis dus aux environnements et autres informations de debug codés en dur.
• Lisibilité: Quiconque ouvrant le code source aura une description détaillée des entrées attendus et le rôle de la tâche. Le temps de maintenance du à la compréhension et au debug du code est ainsi grandement diminué.

Créons notre première tâche

Dans le répertoire de votre projet symfony 1.1, tapez:

$ php symfony generate:task doNothing

Cela créera une tâche vide dans lib/task/doNothingTask.class.php. Améliorons-la un peu.

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

Pour l'instant, cette tâche ne fait pas grand chose, mais elle décrit bien les concepts de base:

• La méthode configure() décrit la tâche. Le nom d'appel, le champ d’action, la syntaxe, l'aide, les options et arguments.
• La méthode execute() effectue le travail proprement dit. Elle est appelé au lancement de la tâche.
• La méthode logSection() peut être utilisé pour afficher des messages sur la console.

Vous pouvez déjà la tester en jouant un peu avec:

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

Un peu d'interaction

Les arguments et les options permettent de fournir des paramètres à la tâche.

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

Nous lançons ici la tâche project:hello-world avec l'option name défini par Romain.

$ php symfony project:hello-world Hi

A présent, nous lançons la même tâche avec comme premier argument, Hi.

Les options et les arguments peuvent avoir des valeurs par défaut, être optionnelles ou requises, et peuvent décrire eux-mêmes leur rôle, qui pourra être indiqué dans la syntaxe de la tâche.

Ecrivons notre tâche project:hello-world:

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

Regardez maintenant comment symfony renseigne l'utilisateur perdu sur l'utilisation cette nouvelle tâche:

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

Jouez également un peu avec les tâches suivantes:

$ 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

Quelques fonctionnalités pratiques

• Besoin de la couche d'abstraction de base de données?

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

• Lancer une autre tâche dans tâche?

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

• Besoin de proposer à l'utilisateur l'environnement à utiliser tout en gérant une valeur par défaut?

  Ajoutez simplement l'option env dans la méthode configure() et symfony utilisera cette valeur comme environnement.

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

C'est la cerise sur le gâteau vous ne trouvez pas? Où plutôt, quelques touches jazzy sur fond de symphonie!