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/>.
  16
  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;
  26
  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 {
  33
  34     /** @var string $hour - Pattern to work out the valid hours */
  35     private $hour = '*';
  36
  37     /** @var string $minute - Pattern to work out the valid minutes */
  38     private $minute = '*';
  39
  40     /** @var string $day - Pattern to work out the valid days */
  41     private $day = '*';
  42
  43     /** @var string $month - Pattern to work out the valid months */
  44     private $month = '*';
  45
  46     /** @var string $dayofweek - Pattern to work out the valid dayofweek */
  47     private $dayofweek = '*';
  48
  49     /** @var int $lastruntime - When this task was last run */
  50     private $lastruntime = 0;
  51
  52     /** @var boolean $customised - Has this task been changed from it's default schedule? */
  53     private $customised = false;
  54
  55     /** @var int $disabled - Is this task disabled in cron? */
  56     private $disabled = false;
  57
  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     }
  65
  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     }
  73
  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     }
  81
  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     }
  89
  90     /**
  91      * Setter for $minute.
  92      * @param string $minute
  93      */
  94     public function set_minute($minute) {
  95         $this->minute = $minute;
  96     }
  97
  98     /**
  99      * Getter for $minute.
 100      * @return string
 101      */
 102     public function get_minute() {
 103         return $this->minute;
 104     }
 105
 106     /**
 107      * Setter for $hour.
 108      * @param string $hour
 109      */
 110     public function set_hour($hour) {
 111         $this->hour = $hour;
 112     }
 113
 114     /**
 115      * Getter for $hour.
 116      * @return string
 117      */
 118     public function get_hour() {
 119         return $this->hour;
 120     }
 121
 122     /**
 123      * Setter for $month.
 124      * @param string $month
 125      */
 126     public function set_month($month) {
 127         $this->month = $month;
 128     }
 129
 130     /**
 131      * Getter for $month.
 132      * @return string
 133      */
 134     public function get_month() {
 135         return $this->month;
 136     }
 137
 138     /**
 139      * Setter for $day.
 140      * @param string $day
 141      */
 142     public function set_day($day) {
 143         $this->day = $day;
 144     }
 145
 146     /**
 147      * Getter for $day.
 148      * @return string
 149      */
 150     public function get_day() {
 151         return $this->day;
 152     }
 153
 154     /**
 155      * Setter for $dayofweek.
 156      * @param string $dayofweek
 157      */
 158     public function set_day_of_week($dayofweek) {
 159         $this->dayofweek = $dayofweek;
 160     }
 161
 162     /**
 163      * Getter for $dayofweek.
 164      * @return string
 165      */
 166     public function get_day_of_week() {
 167         return $this->dayofweek;
 168     }
 169
 170     /**
 171      * Setter for $disabled.
 172      * @param bool $disabled
 173      */
 174     public function set_disabled($disabled) {
 175         $this->disabled = (bool)$disabled;
 176     }
 177
 178     /**
 179      * Getter for $disabled.
 180      * @return bool
 181      */
 182     public function get_disabled() {
 183         return $this->disabled;
 184     }
 185
 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     }
 194
 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);
 206
 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.
 214
 215         // This function is complicated but is covered by unit tests.
 216         $range = array();
 217
 218         $matches = array();
 219         preg_match_all('@[0-9]+|\*|,|/|-@', $field, $matches);
 220
 221         $last = 0;
 222         $inrange = false;
 223         $instep = false;
 224
 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         }
 254
 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     }
 274
 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         }
 294
 295         return 0;
 296     }
 297
 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;
 304
 305         $validminutes = $this->eval_cron_field($this->minute, 0, 59);
 306         $validhours = $this->eval_cron_field($this->hour, 0, 23);
 307
 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         }
 313
 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');
 319
 320         $currentminute = date("i") + 1;
 321         $currenthour = date("H");
 322         $currentday = date("j");
 323         $currentmonth = date("n");
 324         $currentdayofweek = date("w");
 325
 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         }
 341
 342         $daysincrementbyweek = $nextvaliddayofweek - $currentdayofweek;
 343         if ($nextvaliddayofweek < $currentdayofweek) {
 344             $daysincrementbyweek += 7;
 345         }
 346
 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         }
 361
 362         $nextvaliddayofmonth = $currentday + $daysincrement;
 363         if ($nextvaliddayofmonth > $daysinmonth) {
 364             $currentmonth += 1;
 365             $nextvaliddayofmonth -= $daysinmonth;
 366         }
 367
 368         $nextvalidmonth = $this->next_in_list($currentmonth, $validmonths);
 369         if ($nextvalidmonth < $currentmonth) {
 370             $nextvalidyear += 1;
 371         }
 372
 373         // Work out the next valid time.
 374         $nexttime = mktime($nextvalidhour,
 375                            $nextvalidminute,
 376                            0,
 377                            $nextvalidmonth,
 378                            $nextvaliddayofmonth,
 379                            $nextvalidyear);
 380
 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         }
 385
 386         return $nexttime;
 387     }
 388
 389     /**
 390      * Get a descriptive name for this task (shown to admins).
 391      *
 392      * @return string
 393      */
 394     public abstract function get_name();
 395
 396 }