Strangebuzz...?

Hi symfonians !

Again, that's quiet a long i didn't post something on symfony. Well i suppose releasing a new is a good occasion for this. Let me introduce the sfTaskLoggerPlugin plugin:

The sfTaskLoggerPlugin plugin allows you to run tasks and store the results. Results are stored in the database in a specific table and also in a log file. Each task has its own log file, witch is stored in a specific directory depending on its namespace and name. (`/log/tasks/:TASK_NAMESPACE/:TASK_NAME`).

The database record stores the following informations:

• Options of the task
• Arguments of the task
• An error code
• Start and end time
• A success flag
• The log file path
• Extra comments (for admin)

It's very useful, I've already used on several project i worked on (from 1.0 to 1.2). You to have a clean and "easy to access" historic (through an admin gen module for example) of all run tasks and their results. How to use it ? Well Very easy !!

• The official README in Markdown synthax (witch is more readable)

Note: The plugin is Doctrine and Propel friendly, it you are using Doctrine, the /lib/config/doctrine/schema.yml will be used whereas using Propel the /lib/config/schema.yml will be used.

Installation

• Install the plugin

       $ symfony plugin:install sfTaskLoggerPlugin

(or download it and unzip in your /plugins directory)

• Clear you cache

       $ symfony cc

Configuration

The plugin comes with a base task class witch is named sfBaseTaskLoggerTask Therefore your tasks must extend this one. Because there is no autoloading at the task level, one must include the base class manually:

   require_once(dirname(FILE). '/sfBaseTaskLoggerTask.class.php');

Note: Of course you will have to change this path depending on where is located your task. For example if it is located in the `/lib/task` folder of your project, the include directive should look like this:

   require_once(dirname(FILE). '/../../plugins/sfTaskLoggerPlugin/lib/task/sfBaseTaskLoggerTask.class.php');

Usage

1 - Create a new class that extends the plugin base class:

<?php
class sfTaskLoggerSampleTask extends sfBaseTaskLoggerTask
?>

2 - Implement the configure() method as you would do with a standard task:

<?php
/**
 * Main task configuration.
 */
protected function configure()
{
  $this->addArguments(array(
    new sfCommandArgument('arg_1', sfCommandArgument::OPTIONAL, 'Test argument 1', 'arg_1_value'),
    new sfCommandArgument('arg_2', sfCommandArgument::OPTIONAL, 'Test argument 2', 'arg_2_value'),
  ));

  $this->addOptions(array(
    new sfCommandOption('env', null, sfCommandOption::PARAMETER_REQUIRED, 'Environment used', 'prod'),
    new sfCommandOption('application', null, sfCommandOption::PARAMETER_REQUIRED, 'Application used', 'frontend'),
  ));

  $this->namespace = 'sf_task_logger';
  $this->name      = 'sample';

  $this->briefDescription = 'This is a sample task !';

  $this->detailedDescription = <<<EOF
The task [sf_task_logger:sample|INFO] doesn't do that much.
It logs itself in the database and in the file system:

  [./symfony sf_task_logger:sample --env=prod|INFO]
EOF;
}
?>

Now there are 2 specific methods to implement:

3 - checkParameters()

<?php

        /**
         * Advanced check of task parameters.
         */
        protected function checkParameters($arguments = array(), $options = array())
        {
          /* // Stupid example test
          if ($this->args['arg_1'] != 'arg_1_value')
          {
            throw new InvalidArgumentException('The value for argument 1 is not valid ! Check the help of the task.');
          }
          */
    
          return true;
        }
?>

Note: This method can be usefull if you have advanced controls to do on task parameters or arguments. Just return `true` if you don't have to use it.

4 - doProcess()

<?php
        /**
         * Main task process.
         */
        protected function doProcess()
        {
          try
          {
            $this->printAndLog(' - This is a log info !!');
            $this->task->setErrorCode(self::ERROR_CODE_SUCCESS);
            $this->setOk();
          }
          catch (Exception $e)
          {
            $this->task->setErrorCode(self::ERROR_CODE_FAILURE);
            $this->setNOk($e);
          }
        }
?>

Note: This is the main method of your task process. `$this->task` is the database object that will be saved. As you can see the `setOk()` and `setNOk` methods allow to set the flag of the record automatically depending on the success or failure of the task.

If you want more control on the task process you can also re-implement the `execute()` method of the base class witch is responsible for calling all others sub functions:

<?php
    /**
     * Global process of the task.
     *
     * @see sfTask
     */
    protected function execute($arguments = array(), $options = array())
    {
      $this->setParameters($arguments, $options);
    
      $this->checkParameters($arguments, $options);
    
      $this->initDatabaseManager();
    
      $this->initLogger();
    
      $this->logStart();
    
      $this->doProcess();
    
      $this->logEnd();
    }
?>

Notes:

The plugin is bundled with a sample task: `/lib/task/sfTaskLoggerSampleTask.class` witch can be run with the following command:

   ./symfony sf_task_logger:sample

TODO

• Include Propel and Doctrine admin generator module

Support

Please report bugs or feature request on this post.

Changelog

• Check the changelog tab of the plugin tab.

See you. COil

PS: I have published this tutorial quiet quickly, please help me by reporting typos and errors.
PS2: The official README file is far more readable
PS3: As always, any contribution will be welcome !