API.txt

   1 You can extend cron functionality in you modules by using elysia_cron api.
   2 With it you can:
   3 - have more than one cron job per module
   4 - have a different schedule rule for each cron job defined
   5 - set a description for each cron job
   6
   7 To do this you should add in you module a new hook. This is the syntax:
   8
   9 function hook_cronapi($op, $job = NULL) {
  10   $items['key'] = array(
  11     'description' => 'string',
  12     'rule' => 'string',
  13     'weight' => 1234,
  14     'callback' => 'function_name',
  15     'arguments' => array(...),
  16     'file' => 'string', // External file, like hook_menu
  17     'file path' => 'string'
  18   );
  19   $items['key2'] = ...
  20   ...
  21   return $items;
  22 }
  23
  24 - 'key' is the identifier for the task you are defining.
  25   You can define a timing for the standard cron hook of the module by using
  26   the "MODULENAME_cron" key. (See examples).
  27
  28 - description: a textual description of the job, used in elysia cron's status
  29   page.
  30
  31 - rule: the crontab rule. For example: "*/30 * * * *" to execute the task every
  32   30 minutes.
  33
  34 - weight (optional): a numerical value to define order of execution. (Default:0)
  35
  36 - callback (optional): you can define here a name of a PHP function that should
  37   by called to execute the task. This is not mandatory: if you don't specify
  38   it Elysia cron will search for a function called like the task KEY.
  39   If this function is not found, Elysia cron will call the "hook_cronapi"
  40   function with $op = 'execute' and $job = 'KEY' (the key of the task).
  41   (See examples)
  42
  43 - arguments (optional): an array of arguments passed to callback (only if
  44   callback is defined)
  45
  46 - file/file path: the PHP file that contains the callback (hook_menu's syntax)
  47
  48
  49 -----------------------------------------------------------------------------
  50 EXAMPLES
  51 -----------------------------------------------------------------------------
  52
  53 Some examples...
  54
  55 Example 1: Basic
  56 -----------------
  57
  58 example.module:
  59
  60 function example_cronapi($op, $job = NULL) {
  61
  62   $items['example_sendmail_cron'] = array(
  63     'description' => 'Send mail with news',
  64     'rule' => '0 */2 * * *', // Every 2 hours
  65     // Note: i don't need to define a callback, i'll use "example_sendmail_cron"
  66     // function
  67   );
  68
  69   $items['example_news_cron'] = array(
  70     'description' => 'Send mail with news',
  71     'rule' => '*/5 * * * *', // Every 5 minutes
  72     // i must call: example_news_fetch('all')
  73     'callback' => 'example_news_fetch',
  74     'arguments' => array('all'),
  75   );
  76
  77   return $items;
  78 }
  79
  80 function example_sendmail_cron() {
  81   // ...
  82 }
  83
  84 function example_news_fetch($what) {
  85   // ...
  86 }
  87
  88 Example 2: Embedded code
  89 -------------------------
  90
  91 function example_cronapi($op, $job = NULL) {
  92   if ($op == 'list') {
  93     $items['job1'] = array(
  94       'description' => 'Send mail with news',
  95       'rule' => '0 */2 * * *', // Every 2 hours
  96     );
  97
  98     $items['job2'] = array(
  99       'description' => 'Send mail with news',
 100       'rule' => '*/5 * * * *', // Every 5 minutes
 101     );
 102
 103   }
 104   elseif ($op == 'execute') {
 105     switch ($job) {
 106       case 'job1':
 107         // ... job1 code
 108         break;
 109
 110       case 'job2':
 111         // ... job2 code
 112         break;
 113     }
 114   }
 115
 116   return $items;
 117 }
 118
 119
 120 -----------------------------------------------------------------------------
 121 ALTERING HOOK CRON DEFINITION
 122 -----------------------------------------------------------------------------
 123
 124 You can use the "hook_cron_alter" function to edit cronapi data of other
 125 modules.
 126
 127 Example:
 128 function module_cron_alter($data) {
 129   $data['key']['rule'] = '0 */6 * * *';
 130 }
 131
 132
 133 -----------------------------------------------------------------------------
 134 HANDLING DEFAULT MODULE_CRON FUNCTION
 135 -----------------------------------------------------------------------------
 136
 137 To support standard drupal cron, all cron hooks (*_cron function) are
 138 automatically added to supported jobs, even if you don't declare them
 139 on cronapi hook (or if you don't implement the hook at all).
 140 However you can define job description and job rule in the same way as
 141 above (considering the job as an external function).
 142
 143 Example:
 144
 145 function module_cronapi($op, $job = NULL) {
 146   $items['module_cron'] = array(
 147     'description' => 'Standard cron process',
 148     'rule' => '*/15 * * * *',
 149   )
 150   return $items;
 151 }
 152
 153 function module_cron() {
 154   ...
 155   // this is the standard cron hook, but with cronapi above
 156   // it has a default rule (execution every 15 minutes) and
 157   // a description
 158   ...
 159 }
 160
 161
 162 -----------------------------------------------------------------------------
 163 THEMING & JOB DESCRIPTION
 164 -----------------------------------------------------------------------------
 165
 166 If you want to have a nicer cron administration page with all modules
 167 description, and assuming only a few modules supports cronapi hooks,
 168 you can add your own description by script (see above) or by
 169 'elysia_cron_description' theme function.
 170
 171 For example, in your phptemplate theme, you can declare:
 172
 173 function phptemplate_elysia_cron_description($job) {
 174   switch($job) {
 175     case 'job 1': return 'First job';
 176     case 'job 2': return 'Second job';
 177     default: return theme_elysia_cron_description($job);
 178   }
 179 }
 180
 181 Note: module default theme_elysia_cron_description($job) already contains
 182 some common tasks descriptions.
 183
 184
 185 -----------------------------------------------------------------------------
 186 OLD 1.x MODULE API (OBSOLETE)
 187 -----------------------------------------------------------------------------
 188
 189 Elysia Cron 2.0 defines the totally new module API you see above. However the
 190 compatibility with old API is mantained.
 191 This is the old format for reference.
 192
 193 function module_cronapi($op, $job = NULL) {
 194   ...
 195 }
 196
 197 $op can have 3 values:
 198 - 'list': you should return the list of available jobs, in the form
 199   array(
 200     array( 'job' => 'description' ),
 201     array( 'job' => 'description' ),
 202     ...
 203   )
 204   'job' could be the name of a real function or an identifier used with
 205   $op = 'execute' (see below).
 206   Warn: 'job' should be a unique identified, even if it's not a function
 207   name.
 208 - 'rule' : when called with this method, $job variable will contain the
 209   job name you should return the crun rule of.
 210   The rule you return is the default/module preferred schedule rule.
 211   An administrator can always override it to fit his needs.
 212 - 'execute' : when the system needs to call the job task, if no function
 213   with the same of the job exists, it will call the cronapi with this
 214   value and with $job filled with the name of the task to execute.
 215
 216 Example:
 217 Assume your module needs 2 cron tasks: one executed every hour (process_queue)
 218 and one executed once a day (send_summary_mail).
 219 You can do this with this cronapi:
 220
 221 function module_cronapi($op, $job = NULL) {
 222   switch ($op) {
 223     case 'list':
 224       return array(
 225         'module_process_queue' => 'Process queue of new data',
 226         'module_send_summary_mail' => 'Send summary of data processed'
 227       );
 228     case 'rule':
 229       if ($job == 'module_process_queue') return '0 * * * *';
 230       else return '0 1 * * *';
 231     case 'execute':
 232       if ($job == 'module_process_queue') {
 233         ... do the job ...
 234       }
 235       // Just for example, module_send_summary_mail is on a separate
 236       // function (see below)
 237   }
 238 }
 239
 240 function module_send_summary_mail() {
 241   ... do the job ...
 242 }