Scheduling 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.
Examples

This sample code adds a periodic task to the scheduler. The following methods of pm_Scheduler_Task are used:

The code 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. 

 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.