You are here

API.txt in Elysia Cron 5.2

Same filename and directory in other branches
  1. 5 API.txt
  2. 6.2 API.txt
  3. 6 API.txt
  4. 7.2 API.txt
  5. 7 API.txt
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.

- 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 ...
}

File

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