weekly release 2.8dev
[moodle.git] / lib / classes / task / scheduled_task.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Scheduled task abstract class.
19  *
20  * @package    core
21  * @category   task
22  * @copyright  2013 Damyon Wiese
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
25 namespace core\task;
27 /**
28  * Abstract class defining a scheduled task.
29  * @copyright  2013 Damyon Wiese
30  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
31  */
32 abstract class scheduled_task extends task_base {
34     /** @var string $hour - Pattern to work out the valid hours */
35     private $hour = '*';
37     /** @var string $minute - Pattern to work out the valid minutes */
38     private $minute = '*';
40     /** @var string $day - Pattern to work out the valid days */
41     private $day = '*';
43     /** @var string $month - Pattern to work out the valid months */
44     private $month = '*';
46     /** @var string $dayofweek - Pattern to work out the valid dayofweek */
47     private $dayofweek = '*';
49     /** @var int $lastruntime - When this task was last run */
50     private $lastruntime = 0;
52     /** @var boolean $customised - Has this task been changed from it's default schedule? */
53     private $customised = false;
55     /** @var int $disabled - Is this task disabled in cron? */
56     private $disabled = false;
58     /**
59      * Get the last run time for this scheduled task.
60      * @return int
61      */
62     public function get_last_run_time() {
63         return $this->lastruntime;
64     }
66     /**
67      * Set the last run time for this scheduled task.
68      * @param int $lastruntime
69      */
70     public function set_last_run_time($lastruntime) {
71         $this->lastruntime = $lastruntime;
72     }
74     /**
75      * Has this task been changed from it's default config?
76      * @return bool
77      */
78     public function is_customised() {
79         return $this->customised;
80     }
82     /**
83      * Has this task been changed from it's default config?
84      * @param bool
85      */
86     public function set_customised($customised) {
87         $this->customised = $customised;
88     }
90     /**
91      * Setter for $minute.
92      * @param string $minute
93      */
94     public function set_minute($minute) {
95         $this->minute = $minute;
96     }
98     /**
99      * Getter for $minute.
100      * @return string
101      */
102     public function get_minute() {
103         return $this->minute;
104     }
106     /**
107      * Setter for $hour.
108      * @param string $hour
109      */
110     public function set_hour($hour) {
111         $this->hour = $hour;
112     }
114     /**
115      * Getter for $hour.
116      * @return string
117      */
118     public function get_hour() {
119         return $this->hour;
120     }
122     /**
123      * Setter for $month.
124      * @param string $month
125      */
126     public function set_month($month) {
127         $this->month = $month;
128     }
130     /**
131      * Getter for $month.
132      * @return string
133      */
134     public function get_month() {
135         return $this->month;
136     }
138     /**
139      * Setter for $day.
140      * @param string $day
141      */
142     public function set_day($day) {
143         $this->day = $day;
144     }
146     /**
147      * Getter for $day.
148      * @return string
149      */
150     public function get_day() {
151         return $this->day;
152     }
154     /**
155      * Setter for $dayofweek.
156      * @param string $dayofweek
157      */
158     public function set_day_of_week($dayofweek) {
159         $this->dayofweek = $dayofweek;
160     }
162     /**
163      * Getter for $dayofweek.
164      * @return string
165      */
166     public function get_day_of_week() {
167         return $this->dayofweek;
168     }
170     /**
171      * Setter for $disabled.
172      * @param bool $disabled
173      */
174     public function set_disabled($disabled) {
175         $this->disabled = (bool)$disabled;
176     }
178     /**
179      * Getter for $disabled.
180      * @return bool
181      */
182     public function get_disabled() {
183         return $this->disabled;
184     }
186     /**
187      * Override this function if you want this scheduled task to run, even if the component is disabled.
188      *
189      * @return bool
190      */
191     public function get_run_if_component_disabled() {
192         return false;
193     }
195     /**
196      * Take a cron field definition and return an array of valid numbers with the range min-max.
197      *
198      * @param string $field - The field definition.
199      * @param int $min - The minimum allowable value.
200      * @param int $max - The maximum allowable value.
201      * @return array(int)
202      */
203     public function eval_cron_field($field, $min, $max) {
204         // Cleanse the input.
205         $field = trim($field);
207         // Format for a field is:
208         // <fieldlist> := <range>(/<step>)(,<fieldlist>)
209         // <step>  := int
210         // <range> := <any>|<int>|<min-max>
211         // <any>   := *
212         // <min-max> := int-int
213         // End of format BNF.
215         // This function is complicated but is covered by unit tests.
216         $range = array();
218         $matches = array();
219         preg_match_all('@[0-9]+|\*|,|/|-@', $field, $matches);
221         $last = 0;
222         $inrange = false;
223         $instep = false;
225         foreach ($matches[0] as $match) {
226             if ($match == '*') {
227                 array_push($range, range($min, $max));
228             } else if ($match == '/') {
229                 $instep = true;
230             } else if ($match == '-') {
231                 $inrange = true;
232             } else if (is_numeric($match)) {
233                 if ($instep) {
234                     $i = 0;
235                     for ($i = 0; $i < count($range[count($range) - 1]); $i++) {
236                         if (($i) % $match != 0) {
237                             $range[count($range) - 1][$i] = -1;
238                         }
239                     }
240                     $inrange = false;
241                 } else if ($inrange) {
242                     if (count($range)) {
243                         $range[count($range) - 1] = range($last, $match);
244                     }
245                     $inrange = false;
246                 } else {
247                     if ($match >= $min && $match <= $max) {
248                         array_push($range, $match);
249                     }
250                     $last = $match;
251                 }
252             }
253         }
255         // Flatten the result.
256         $result = array();
257         foreach ($range as $r) {
258             if (is_array($r)) {
259                 foreach ($r as $rr) {
260                     if ($rr >= $min && $rr <= $max) {
261                         $result[$rr] = 1;
262                     }
263                 }
264             } else if (is_numeric($r)) {
265                 if ($r >= $min && $r <= $max) {
266                     $result[$r] = 1;
267                 }
268             }
269         }
270         $result = array_keys($result);
271         sort($result, SORT_NUMERIC);
272         return $result;
273     }
275     /**
276      * Assuming $list is an ordered list of items, this function returns the item
277      * in the list that is greater than or equal to the current value (or 0). If
278      * no value is greater than or equal, this will return the first valid item in the list.
279      * If list is empty, this function will return 0.
280      *
281      * @param int $current The current value
282      * @param int[] $list The list of valid items.
283      * @return int $next.
284      */
285     private function next_in_list($current, $list) {
286         foreach ($list as $l) {
287             if ($l >= $current) {
288                 return $l;
289             }
290         }
291         if (count($list)) {
292             return $list[0];
293         }
295         return 0;
296     }
298     /**
299      * Calculate when this task should next be run based on the schedule.
300      * @return int $nextruntime.
301      */
302     public function get_next_scheduled_time() {
303         global $CFG;
305         $validminutes = $this->eval_cron_field($this->minute, 0, 59);
306         $validhours = $this->eval_cron_field($this->hour, 0, 23);
308         // We need to change to the server timezone before using php date() functions.
309         $origtz = date_default_timezone_get();
310         if (!empty($CFG->timezone) && $CFG->timezone != 99) {
311             date_default_timezone_set($CFG->timezone);
312         }
314         $daysinmonth = date("t");
315         $validdays = $this->eval_cron_field($this->day, 1, $daysinmonth);
316         $validdaysofweek = $this->eval_cron_field($this->dayofweek, 0, 7);
317         $validmonths = $this->eval_cron_field($this->month, 1, 12);
318         $nextvalidyear = date('Y');
320         $currentminute = date("i") + 1;
321         $currenthour = date("H");
322         $currentday = date("j");
323         $currentmonth = date("n");
324         $currentdayofweek = date("w");
326         $nextvalidminute = $this->next_in_list($currentminute, $validminutes);
327         if ($nextvalidminute < $currentminute) {
328             $currenthour += 1;
329         }
330         $nextvalidhour = $this->next_in_list($currenthour, $validhours);
331         if ($nextvalidhour < $currenthour) {
332             $currentdayofweek += 1;
333             $currentday += 1;
334         }
335         $nextvaliddayofmonth = $this->next_in_list($currentday, $validdays);
336         $nextvaliddayofweek = $this->next_in_list($currentdayofweek, $validdaysofweek);
337         $daysincrementbymonth = $nextvaliddayofmonth - $currentday;
338         if ($nextvaliddayofmonth < $currentday) {
339             $daysincrementbymonth += $daysinmonth;
340         }
342         $daysincrementbyweek = $nextvaliddayofweek - $currentdayofweek;
343         if ($nextvaliddayofweek < $currentdayofweek) {
344             $daysincrementbyweek += 7;
345         }
347         // Special handling for dayofmonth vs dayofweek:
348         // if either field is * - use the other field
349         // otherwise - choose the soonest (see man 5 cron).
350         if ($this->dayofweek == '*') {
351             $daysincrement = $daysincrementbymonth;
352         } else if ($this->day == '*') {
353             $daysincrement = $daysincrementbyweek;
354         } else {
355             // Take the smaller increment of days by month or week.
356             $daysincrement = $daysincrementbymonth;
357             if ($daysincrementbyweek < $daysincrementbymonth) {
358                 $daysincrement = $daysincrementbyweek;
359             }
360         }
362         $nextvaliddayofmonth = $currentday + $daysincrement;
363         if ($nextvaliddayofmonth > $daysinmonth) {
364             $currentmonth += 1;
365             $nextvaliddayofmonth -= $daysinmonth;
366         }
368         $nextvalidmonth = $this->next_in_list($currentmonth, $validmonths);
369         if ($nextvalidmonth < $currentmonth) {
370             $nextvalidyear += 1;
371         }
373         // Work out the next valid time.
374         $nexttime = mktime($nextvalidhour,
375                            $nextvalidminute,
376                            0,
377                            $nextvalidmonth,
378                            $nextvaliddayofmonth,
379                            $nextvalidyear);
381         // We need to change the timezone back so other date functions in moodle do not get confused.
382         if (!empty($CFG->timezone) && $CFG->timezone != 99) {
383             date_default_timezone_set($origtz);
384         }
386         return $nexttime;
387     }
389     /**
390      * Get a descriptive name for this task (shown to admins).
391      *
392      * @return string
393      */
394     public abstract function get_name();