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.