Fix cron running every minute
[project/elysia_cron.git] / 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 }