Tasks

Evan Tahler edited this page Apr 17, 2011 · 3 revisions

DAVE makes use of a "task" framework to create management or periodic actions. DAVE's task structure were heavily inspired by the RAKE framework for Ruby on Rails.

Some examples of tasks might include:

  • Cleaning up LOG actions stored in the data base
  • Removing Log Files or Archiving them
  • Sending Emails queued in the data base.

Tasks can be run either from the command line or by other portions of the API codebase (CRON.php uses tasks, for example)

Creating Tasks

Tasks live in the /API/Tasks folder. Tasks inherit the task class found in /API/Tasks/_BASE.php. A basic task looks like this:

class MyNewTask extends task
{       
    protected static $description = "I AM THE DESCRIPTION OF THIS TASK";

    public function run($PARAMS = array())
    {
        global $CONFIG, $DBObj;

        // PUT YOUR ACTION CODE HERE

        // collect output with the task_log method
        // $this->task_log('Task Complete!');
    }
}

Tasks will be run within the normal API environment, so $CONFIG and $DBObj are available to it. run() is required to be the main method to run the task, although other methods can be created as needed. The Task's name is derived both the file name and the class name. It is important that these both match!

Command Line Use

Tasks are executed from the command line via /API/TASKs.php. You may list all the available tasks known to the API with php API/TASKS.php --list (or -- help). To run a task, use the --task= or -t= flag, for example php API/TASKS.php --t=CleanCache. Any additional parameters your Task might expect are passed in key/value style like the name of the task, for example php API/TASKS.php -t=TruncateTable --table=LOG --DB=daveapi_log.

Tasks may be called manually by developers, or other components of your web hosting infrastructure via the shell.

In-Code Use

When instantiating a task class, you may pass the autorun flag as the first parameter, and any optional parameters your task might need: $Task = new MyTask('true',$PARAMS). If a Task class is called with true passed as the first parameter when instantiating, it will run the run() method automatically. Otherwise, you can always call run() on the task when you wish to run it.

There is a CommonFunction, load_tasks() which will load all the tasks found in API/Tasks into memory, and will return an array of available tasks. There is another CommonFunction which makes it simple to run a task, run_task(). This method optionally accepts an array of PARAMS to pass to the Task. This method will run the Task inline, and return the internal TaskLog as a string. It is a good idea to keep the default CRON Tasks which come with this API, otherwise your log data may get very large. Here is the content of the default CRON.php as of this writing.

$parts = explode("/",__FILE__);
$ThisFile = $parts[count($parts) - 1];
chdir(substr(__FILE__,0,(strlen(__FILE__) - strlen($ThisFile))));
require_once("load_enviorment.php"); unset($parts); unset($ThisFile);

load_tasks();

$CRON_OUTPUT = "STARTING CRON @ ".date("m-d-Y H:i:s")."\r\n\r\n";

/////////////////////////////////////////////////////////////////////////
// Do Tasks

$CRON_OUTPUT .= run_task("CleanCache");
$CRON_OUTPUT .= run_task("CleanLog");
$CRON_OUTPUT .= run_task("CleanSessions");
$CRON_OUTPUT .= run_task("RemoveLargeLogs");

/////////////////////////////////////////////////////////////////////////
// End the log output
echo $CRON_OUTPUT;
$fh = fopen($CONFIG['CronLogFile'], 'a');
fwrite($fh, $CRON_OUTPUT);
fclose($fh);

exit;

You can collect the output of the task from it's internal log with the get_task_log() method. It will return a formatted multi-line string.

A task can internally check the status of $DBObj with the check_DBObj() method. It will return true upon success, or a failure message.

You can always retrieve the Task's name and description with the ClassName::class_name and ClassName::get_description static methods.