Scheduled Tasks

An extension can run some of its routines periodically, for example, every 10 minutes, every hour, or daily. This scheduler interface manages the crontab utility on Linux and the Task Scheduler application on Windows. The interface is presented by two classes - pm_Scheduler and pm_Scheduler_Task. The first class represents a task manager and the second class represents a task.

To successfully schedule a task, your code must meet the following requirements:

• Put a scheduled task under /plib/scripts/ relatively to the extension's root directory.
• Initialize the extension context (pm_Context::init) before scheduling a task.
• Schedule the task using pm_Scheduler and pm_Scheduler_Task.

Usage Examples

A sample code that adds a periodic task to the scheduler can look as follows:

$task = new pm_Scheduler_Task();
$task->setSchedule(array(
    'minute' => '0,4,9,14,19,24,29,34,39,44,49,54,59',
    'hour' => '*',
    'dom' => '*',
    'month' => '*',
    'dow' => '*'
    ));
$task->setCmd('five-minutes-task.php');
pm_Context::init('extension-id');
pm_Scheduler::getInstance()->putTask($task);  
var_dump($task->getId()); // Save task id in order to remove it if necessary

See an example of using scheduled tasks in Exercise 2.

Designing a Run Schedule

When designing a run schedule, you should pay attention to the following operating-system differences:

• On Linux, the schedule may be specified in the cron format. Learn more about the format at: http://www.nncron.ru/help/EN/working/cron-format.htm.
• On Windows, the schedule may be set by using commas (,) and asterisks (*).
• We recommend that you use the following cross-platform constants when defining a period between two task runs:

  pm_Scheduler::$EVERY_MIN

  pm_Scheduler::$EVERY_5_MIN

  pm_Scheduler::$EVERY_10_MIN

  pm_Scheduler::$EVERY_HOUR

  pm_Scheduler::$EVERY_DAY

  pm_Scheduler::$EVERY_WEEK

  pm_Scheduler::$EVERY_MONTH

• On Windows, a task is limited to 48 different start conditions (triggers). Learn more about triggers and the limitation at:
  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383619%28v=vs.85%29.aspx

Listing Tasks

If you need to loop through scheduled tasks, do it in the following way:

$tasks = pm_Scheduler::getInstance()->listTasks();
foreach ($tasks as $task) {
    var_dump($task->getId());
    var_dump($task->getSchedule());
    var_dump($task->getCmd());
}

Removing Scheduled Tasks

We highly recommend that you save IDs of your scheduled tasks to the key-value storage and then remove the tasks during the removal of your extension. The following code removes a task:

$task = pm_Scheduler::getInstance()->getTaskById('64daef15d48e0fe038bb20a77a171150');
pm_Scheduler::getInstance()->removeTask($task);

Passing Arguments to Tasks

If you need to pass certain arguments to a task, use the setArguments method. The following code creates a task with arguments:

$task = new pm_Scheduler_Task();
$task->setSchedule(pm_Scheduler::$EVERY_DAY);
$task->setCmd('send-daily-report.php');
$task->setArguments(array('john', 'robert', 'ivan'));
pm_Scheduler::getInstance()->putTask($task);

To retrieve a task's arguments, use the getArguments method, for example, in the following way:

var_dump($task->getArguments());

 

Note that a task ID is assigned by the putTask method.