244 lines
7.1 KiB
Plaintext
244 lines
7.1 KiB
Plaintext
You can extend cron functionality in you modules by using elysia_cron api.
|
|
With it you can:
|
|
- have more than one cron job per module
|
|
- have a different schedule rule for each cron job defined
|
|
- set a description for each cron job
|
|
|
|
To do this you should add in you module a new hook. This is the syntax:
|
|
|
|
function hook_cronapi($op, $job = NULL) {
|
|
$items['key'] = array(
|
|
'description' => 'string',
|
|
'rule' => 'string',
|
|
'weight' => 1234,
|
|
'callback' => 'function_name',
|
|
'arguments' => array(...),
|
|
'file' => 'string', // External file, like hook_menu
|
|
'file path' => 'string'
|
|
);
|
|
$items['key2'] = ...
|
|
...
|
|
return $items;
|
|
}
|
|
|
|
- 'key' is the identifier for the task you are defining.
|
|
You can define a timing for the standard cron hook of the module by using
|
|
the "MODULENAME_cron" key. (See examples).
|
|
|
|
- description: a textual description of the job, used in elysia cron's status
|
|
page. Use the untranslated string, without the "t()" wrapper (elysia_cron
|
|
will apply it)
|
|
|
|
- rule: the crontab rule. For example: "*/30 * * * *" to execute the task every
|
|
30 minutes.
|
|
|
|
- weight (optional): a numerical value to define order of execution. (Default:0)
|
|
|
|
- callback (optional): you can define here a name of a PHP function that should
|
|
by called to execute the task. This is not mandatory: if you don't specify
|
|
it Elysia cron will search for a function called like the task KEY.
|
|
If this function is not found, Elysia cron will call the "hook_cronapi"
|
|
function with $op = 'execute' and $job = 'KEY' (the key of the task).
|
|
(See examples)
|
|
|
|
- arguments (optional): an array of arguments passed to callback (only if
|
|
callback is defined)
|
|
|
|
- file/file path: the PHP file that contains the callback (hook_menu's syntax)
|
|
|
|
|
|
-----------------------------------------------------------------------------
|
|
EXAMPLES
|
|
-----------------------------------------------------------------------------
|
|
|
|
Some examples...
|
|
|
|
Example 1: Basic
|
|
-----------------
|
|
|
|
example.module:
|
|
|
|
function example_cronapi($op, $job = NULL) {
|
|
|
|
$items['example_sendmail_cron'] = array(
|
|
'description' => 'Send mail with news',
|
|
'rule' => '0 */2 * * *', // Every 2 hours
|
|
// Note: i don't need to define a callback, i'll use "example_sendmail_cron"
|
|
// function
|
|
);
|
|
|
|
$items['example_news_cron'] = array(
|
|
'description' => 'Send mail with news',
|
|
'rule' => '*/5 * * * *', // Every 5 minutes
|
|
// i must call: example_news_fetch('all')
|
|
'callback' => 'example_news_fetch',
|
|
'arguments' => array('all'),
|
|
);
|
|
|
|
return $items;
|
|
}
|
|
|
|
function example_sendmail_cron() {
|
|
// ...
|
|
}
|
|
|
|
function example_news_fetch($what) {
|
|
// ...
|
|
}
|
|
|
|
Example 2: Embedded code
|
|
-------------------------
|
|
|
|
function example_cronapi($op, $job = NULL) {
|
|
if ($op == 'list') {
|
|
$items['job1'] = array(
|
|
'description' => 'Send mail with news',
|
|
'rule' => '0 */2 * * *', // Every 2 hours
|
|
);
|
|
|
|
$items['job2'] = array(
|
|
'description' => 'Send mail with news',
|
|
'rule' => '*/5 * * * *', // Every 5 minutes
|
|
);
|
|
|
|
}
|
|
elseif ($op == 'execute') {
|
|
switch ($job) {
|
|
case 'job1':
|
|
// ... job1 code
|
|
break;
|
|
|
|
case 'job2':
|
|
// ... job2 code
|
|
break;
|
|
}
|
|
}
|
|
|
|
return $items;
|
|
}
|
|
|
|
|
|
-----------------------------------------------------------------------------
|
|
ALTERING HOOK CRON DEFINITION
|
|
-----------------------------------------------------------------------------
|
|
|
|
You can use the "hook_cron_alter" function to edit cronapi data of other
|
|
modules.
|
|
|
|
Example:
|
|
function module_cron_alter($data) {
|
|
$data['key']['rule'] = '0 */6 * * *';
|
|
}
|
|
|
|
|
|
-----------------------------------------------------------------------------
|
|
HANDLING DEFAULT MODULE_CRON FUNCTION
|
|
-----------------------------------------------------------------------------
|
|
|
|
To support standard drupal cron, all cron hooks (*_cron function) are
|
|
automatically added to supported jobs, even if you don't declare them
|
|
on cronapi hook (or if you don't implement the hook at all).
|
|
However you can define job description and job rule in the same way as
|
|
above (considering the job as an external function).
|
|
|
|
Example:
|
|
|
|
function module_cronapi($op, $job = NULL) {
|
|
$items['module_cron'] = array(
|
|
'description' => 'Standard cron process',
|
|
'rule' => '*/15 * * * *',
|
|
)
|
|
return $items;
|
|
}
|
|
|
|
function module_cron() {
|
|
...
|
|
// this is the standard cron hook, but with cronapi above
|
|
// it has a default rule (execution every 15 minutes) and
|
|
// a description
|
|
...
|
|
}
|
|
|
|
|
|
-----------------------------------------------------------------------------
|
|
THEMING & JOB DESCRIPTION
|
|
-----------------------------------------------------------------------------
|
|
|
|
If you want to have a nicer cron administration page with all modules
|
|
description, and assuming only a few modules supports cronapi hooks,
|
|
you can add your own description by script (see above) or by
|
|
'elysia_cron_description' theme function.
|
|
|
|
For example, in your phptemplate theme, you can declare:
|
|
|
|
function phptemplate_elysia_cron_description($job) {
|
|
switch($job) {
|
|
case 'job 1': return 'First job';
|
|
case 'job 2': return 'Second job';
|
|
default: return theme_elysia_cron_description($job);
|
|
}
|
|
}
|
|
|
|
Note: module default theme_elysia_cron_description($job) already contains
|
|
some common tasks descriptions.
|
|
|
|
|
|
-----------------------------------------------------------------------------
|
|
OLD 1.x MODULE API (OBSOLETE)
|
|
-----------------------------------------------------------------------------
|
|
|
|
Elysia Cron 2.0 defines the totally new module API you see above. However the
|
|
compatibility with old API is mantained.
|
|
This is the old format for reference.
|
|
|
|
function module_cronapi($op, $job = NULL) {
|
|
...
|
|
}
|
|
|
|
$op can have 3 values:
|
|
- 'list': you should return the list of available jobs, in the form
|
|
array(
|
|
array( 'job' => 'description' ),
|
|
array( 'job' => 'description' ),
|
|
...
|
|
)
|
|
'job' could be the name of a real function or an identifier used with
|
|
$op = 'execute' (see below).
|
|
Warn: 'job' should be a unique identified, even if it's not a function
|
|
name.
|
|
- 'rule' : when called with this method, $job variable will contain the
|
|
job name you should return the crun rule of.
|
|
The rule you return is the default/module preferred schedule rule.
|
|
An administrator can always override it to fit his needs.
|
|
- 'execute' : when the system needs to call the job task, if no function
|
|
with the same of the job exists, it will call the cronapi with this
|
|
value and with $job filled with the name of the task to execute.
|
|
|
|
Example:
|
|
Assume your module needs 2 cron tasks: one executed every hour (process_queue)
|
|
and one executed once a day (send_summary_mail).
|
|
You can do this with this cronapi:
|
|
|
|
function module_cronapi($op, $job = NULL) {
|
|
switch ($op) {
|
|
case 'list':
|
|
return array(
|
|
'module_process_queue' => 'Process queue of new data',
|
|
'module_send_summary_mail' => 'Send summary of data processed'
|
|
);
|
|
case 'rule':
|
|
if ($job == 'module_process_queue') return '0 * * * *';
|
|
else return '0 1 * * *';
|
|
case 'execute':
|
|
if ($job == 'module_process_queue') {
|
|
... do the job ...
|
|
}
|
|
// Just for example, module_send_summary_mail is on a separate
|
|
// function (see below)
|
|
}
|
|
}
|
|
|
|
function module_send_summary_mail() {
|
|
... do the job ...
|
|
}
|