You are here

API.txt in Elysia Cron 7.2

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

-----------------------------------------------------------------------------
DISABLE CRON JOBS VIA settings.php FILE
-----------------------------------------------------------------------------
If you have some instances for the project you can want to disable some cron
jobs on different instances. For example you don't want to execute PROD cron
jobs on DEV instance. There is no need to make it via interface or via SQL
query. You can define variable for each cron job to manage it state. For more
information please look at `_elysia_cron_is_job_disabled` and `_ec_get_name`
functions.

For example, if you have cron job with name googleanalytics_cron, you can
add this string to your settings.php file:
$conf['ec_googleanalytics_cron_d'] = TRUE;

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