API.txt 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243
  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. OLD 1.x MODULE API (OBSOLETE)
  144. -----------------------------------------------------------------------------
  145. Elysia Cron 2.0 defines the totally new module API you see above. However the
  146. compatibility with old API is mantained.
  147. This is the old format for reference.
  148. function module_cronapi($op, $job = NULL) {
  149. ...
  150. }
  151. $op can have 3 values:
  152. - 'list': you should return the list of available jobs, in the form
  153. array(
  154. array( 'job' => 'description' ),
  155. array( 'job' => 'description' ),
  156. ...
  157. )
  158. 'job' could be the name of a real function or an identifier used with
  159. $op = 'execute' (see below).
  160. Warn: 'job' should be a unique identified, even if it's not a function
  161. name.
  162. - 'rule' : when called with this method, $job variable will contain the
  163. job name you should return the crun rule of.
  164. The rule you return is the default/module preferred schedule rule.
  165. An administrator can always override it to fit his needs.
  166. - 'execute' : when the system needs to call the job task, if no function
  167. with the same of the job exists, it will call the cronapi with this
  168. value and with $job filled with the name of the task to execute.
  169. Example:
  170. Assume your module needs 2 cron tasks: one executed every hour (process_queue)
  171. and one executed once a day (send_summary_mail).
  172. You can do this with this cronapi:
  173. function module_cronapi($op, $job = NULL) {
  174. switch ($op) {
  175. case 'list':
  176. return array(
  177. 'module_process_queue' => 'Process queue of new data',
  178. 'module_send_summary_mail' => 'Send summary of data processed'
  179. );
  180. case 'rule':
  181. if ($job == 'module_process_queue') return '0 * * * *';
  182. else return '0 1 * * *';
  183. case 'execute':
  184. if ($job == 'module_process_queue') {
  185. ... do the job ...
  186. }
  187. // Just for example, module_send_summary_mail is on a separate
  188. // function (see below)
  189. }
  190. }
  191. function module_send_summary_mail() {
  192. ... do the job ...
  193. }