Development

Changeset 8405

You must first sign up to be able to contribute.

Changeset 8405

Show
Ignore:
Timestamp:
04/10/08 23:22:30 (3 months ago)
Author:
francois
Message:

[doc 1.1] Documented task creation via the command line (refs r8404)

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • doc/branches/1.1/book/16-Application-Management-Tools.txt

    r8340 r8405  
    336336-------------------------------------- 
    337337 
    338 You may want to execute a script from the command line (or via a cron table) with access to all the symfony classes and features, for instance to launch batch e-mail jobs or to periodically update your model through a process-intensive calculation. The old way of doing this is to create a PHP script that reproduces the first steps of a front controller, so that symfony is properly initialized. But there is a better way: just create a new symfony command task. Both ways are explained in this section. 
     338You may want to execute a script from the command line (or via a cron table) with access to all the symfony classes and features, for instance to launch batch e-mail jobs or to periodically update your model through a process-intensive calculation. The simple way of doing this is to create a PHP script that reproduces the first steps of a front controller, so that symfony is properly initialized. You can also use the symfony command line system, to take advantage of arguments parsing and automated database initialization. 
    339339 
    340340### Batch Files 
    …… 
    365365    > php lib/myScript.php 
    366366 
    367 >**NOTE** 
    368 >As of symfony 1.0, such scripts would be located under the `batch/` diretory. This directory does not exist anymore in 1.1 projects, and it is advised to write batch scripts as symfony commands to take advantage of the options parsing--see below. 
    369  
    370367### Custom tasks (new in symfony 1.1) 
    371368 
    …… 
    374371A custom task is just a class extending `sfBaseTask` and located under a `lib/task/` directory, either under the project root, or in a plugin directory. Its file name must end with 'Task.class.php'. Listing 16-13 shows a sample custom task. 
    375372 
    376 Listing 16-13 - Sample Task, in `lib/task/myTask.class.php` 
    377  
    378     [php] 
    379  
    380     class myTask extends sfBaseTask 
     373Listing 16-13 - Sample Task, in `lib/task/testHelloTask.class.php` 
     374 
     375    [php] 
     376 
     377    class testHelloTask extends sfBaseTask 
    381378    { 
    382379      protected function configure() 
    383380      { 
    384         $this->name = 'myTask'; 
    385         $this->briefDescription = 'Does some neat things'; 
     381        $this->namespace = 'test'; 
     382        $this->name = 'hello'; 
     383        $this->briefDescription = 'Says hello'; 
    386384      } 
    387385 
    388386      protected function execute() 
    389387      { 
    390         // add code here 
     388        // your code here 
     389        $this->log('Hello, world!'); 
    391390      } 
    392391    } 
    393392 
    394 The code written in the `execute` method will have access to all the symfony libraries, just like in the previous batch script. The difference is how you call the custom task: 
    395  
    396     > php symfony myTask 
    397  
    398 The task names comes from the protected `name` property (not from the class name, nor from the files name). And since your task is integrated into the symfony command line, it appears in the task list when you just type: 
     393The code written in the `execute` method has access to all the symfony libraries, just like in the previous batch script. The difference is how you call the custom task: 
     394 
     395    > php symfony test:hello 
     396 
     397The task name comes from the protected `namespace` and `name` properties (not from the class name, nor from the files name). And since your task is integrated into the symfony command line, it appears in the task list when you just type: 
    399398 
    400399    > php symfony 
    401400 
    402 As for regular classes, you can add a help text: just define the `detailedDescription` property. The help text will be displayed when a user calls `php symfony help myTask`. You can also put your task in a given namespace, to avoid name conflicts. Just define the `namespace` property for that. Last but not least, you can add arguments (compulsory parameters, in a predefined order) and options (optional and unordered parameters) to your command. Listing 16-14 shows a more complete task, taking advantage of all these features. 
     401Rather than writing a task skeleton by yourself, you can use the symfony `task:init` task. It creates an empty task, and has plenty of customization options. Make sure you check them by calling: 
     402 
     403    > php symfony help task:init 
     404 
     405Tasks can accept arguments (compulsory parameters, in a predefined order) and options (optional and unordered parameters). Listing 16-14 shows a more complete task, taking advantage of all these features. 
    403406 
    404407Listing 16-14 - More Complete Sample Task, in `lib/task/mySecondTask.class.php` 
    …… 
    422425      [php symfony foo:mySecondTask frontend --verbose=on|INFO] 
    423426    EOF; 
    424         $this->addArguments(array( 
    425           new sfCommandArgument('application', sfCommandArgument::REQUIRED, 'The application name'), 
    426         )); 
    427         $this->addOptions(array( 
    428           new sfCommandOption('verbose', null, sfCommandOption::PARAMETER_REQUIRED, 'Enables verbose output', false), 
    429         )); 
     427        $this->addArgument('application', sfCommandArgument::REQUIRED, 'The application name'); 
     428        $this->addOption('verbose', null, sfCommandOption::PARAMETER_REQUIRED, 'Enables verbose output', false); 
    430429      } 
    431430 
    …… 
    433432      { 
    434433        // add code here 
     434         
    435435      } 
    436436    } 
    437437 
    438438>**NOTE** 
    439 >If your task needs access to the database layer, it should extend `sfPropelBaseTask` instead of `sfBaseTask`. The task initialization will then take care loading the additional Propel classes. The task can require an `application` and an `environment` argument so that you can start a database connection in the `execute()` method by calling: 
     439>If your task needs access to the database layer, it should extend `sfPropelBaseTask` instead of `sfBaseTask`. The task initialization will then take care of loading the additional Propel classes. The task can require an `application` and an `env` argument so that you can start a database connection in the `execute()` method by calling: 
    440440> 
    441441>    $configuration = ProjectConfiguration::getApplicationConfiguration($arguments['application'], $options['env'], true); 
    442442>    $databaseManager = new sfDatabaseManager($configuration); 
    443443> 
    444  
    445 For more examples on how to create a custom task, check the source of existing symfony tasks. 
     444>By default, skeletons generated by a call to `task:init` include this initialization. 
     445 
     446For more examples on the abilities of the task system, check the source of existing symfony tasks. 
    446447 
    447448If you declare a task with the same name as an existing task, your class overrides the existing task. That means that a plugin can override a symfony task, and that a project can override a plugin task and a symfony task. Add to that the ability to extend an existing task class, and you have a very extensible command line system!