summaryrefslogtreecommitdiffstats
path: root/API.txt
blob: b465ecf0cb7b0dca3adf035f1a8e04adf7632758 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
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 ...
}