Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Scheduled task abstract class.
 *
 * @package    core
 * @category   task
 * @copyright  2013 Damyon Wiese
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
namespace core\task;

/**
 * Abstract class defining a scheduled task.
 * @copyright  2013 Damyon Wiese
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class scheduled_task extends task_base {

    /** Minimum minute value. */
    const MINUTEMIN = 0;
    /** Maximum minute value. */
    const MINUTEMAX = 59;

    /** Minimum hour value. */
    const HOURMIN = 0;
    /** Maximum hour value. */
    const HOURMAX = 23;

> /** Minimum day of month value. */ /** Minimum dayofweek value. */ > const DAYMIN = 1; const DAYOFWEEKMIN = 0; > /** Maximum day of month value. */ /** Maximum dayofweek value. */ > const DAYMAX = 31; const DAYOFWEEKMAX = 6; > > /** Minimum month value. */ /** @var string $hour - Pattern to work out the valid hours */ > const MONTHMIN = 1; private $hour = '*'; > /** Maximum month value. */ > const MONTHMAX = 12; /** @var string $minute - Pattern to work out the valid minutes */ >
private $minute = '*';
> /** Maximum dayofweek value allowed in input (7 = 0). */ > const DAYOFWEEKMAXINPUT = 7; /** @var string $day - Pattern to work out the valid days */ > private $day = '*'; > /** > * Minute field identifier. /** @var string $month - Pattern to work out the valid months */ > */ private $month = '*'; > const FIELD_MINUTE = 'minute'; > /** /** @var string $dayofweek - Pattern to work out the valid dayofweek */ > * Hour field identifier. private $dayofweek = '*'; > */ > const FIELD_HOUR = 'hour'; /** @var int $lastruntime - When this task was last run */ > /** private $lastruntime = 0; > * Day-of-month field identifier. > */ /** @var boolean $customised - Has this task been changed from it's default schedule? */ > const FIELD_DAY = 'day'; private $customised = false; > /** > * Month field identifier. /** @var boolean $overridden - Does the task have values set VIA config? */ > */ private $overridden = false; > const FIELD_MONTH = 'month'; > /** /** @var int $disabled - Is this task disabled in cron? */ > * Day-of-week field identifier. private $disabled = false; > */ > const FIELD_DAYOFWEEK = 'dayofweek'; /** > * Get the last run time for this scheduled task. > /** * @return int > * Time used for the next scheduled time when a task should never run. This is 2222-01-01 00:00 GMT */ > * which is a large time that still fits in 10 digits. public function get_last_run_time() { > */ return $this->lastruntime; > const NEVER_RUN_TIME = 7952342400;
}
> *
/** * Set the last run time for this scheduled task.
> *
* @param int $lastruntime */ public function set_last_run_time($lastruntime) { $this->lastruntime = $lastruntime; } /** * Has this task been changed from it's default config?
> *
* @return bool */ public function is_customised() { return $this->customised; } /**
< * Has this task been changed from it's default config?
> * Set customised for this scheduled task. > *
* @param bool */ public function set_customised($customised) { $this->customised = $customised; } /**
> * Determine if this task is using its default configuration changed from the default. Returns true * Has this task been changed from it's default config? > * if it is and false otherwise. Does not rely on the customised field. * @return bool > * */ > * @return bool public function is_overridden(): bool { > */ return $this->overridden; > public function has_default_configuration(): bool { } > $defaulttask = \core\task\manager::get_default_scheduled_task($this::class); > if ($defaulttask->get_minute() !== $this->get_minute()) { /** > return false; * Set the overridden value. > } * @param bool $overridden > if ($defaulttask->get_hour() != $this->get_hour()) { */ > return false; public function set_overridden(bool $overridden): void { > } $this->overridden = $overridden; > if ($defaulttask->get_month() != $this->get_month()) { } > return false; > } /** > if ($defaulttask->get_day_of_week() != $this->get_day_of_week()) { * Setter for $minute. Accepts a special 'R' value > return false; * which will be translated to a random minute. > } * @param string $minute > if ($defaulttask->get_day() != $this->get_day()) { * @param bool $expandr - if true (default) an 'R' value in a time is expanded to an appropriate int. > return false; * If false, they are left as 'R' > } */ > if ($defaulttask->get_disabled() != $this->get_disabled()) { public function set_minute($minute, $expandr = true) { > return false; if ($minute === 'R' && $expandr) { > } $minute = mt_rand(self::MINUTEMIN, self::MINUTEMAX); > return true; } > } $this->minute = $minute; > } > /** > * Disable the task. /** > */ * Getter for $minute. > public function disable(): void { * @return string > $this->set_disabled(true); */ > $this->set_customised(!$this->has_default_configuration()); public function get_minute() { > \core\task\manager::configure_scheduled_task($this); return $this->minute; > } } > > /** /** > * Enable the task. * Setter for $hour. Accepts a special 'R' value > */ * which will be translated to a random hour. > public function enable(): void { * @param string $hour > $this->set_disabled(false); * @param bool $expandr - if true (default) an 'R' value in a time is expanded to an appropriate int. > $this->set_customised(!$this->has_default_configuration()); * If false, they are left as 'R' > \core\task\manager::configure_scheduled_task($this); */ > } public function set_hour($hour, $expandr = true) { > if ($hour === 'R' && $expandr) { > /**
$hour = mt_rand(self::HOURMIN, self::HOURMAX);
> *
}
> *
$this->hour = $hour;
> *
}
> *
> *
/** * Getter for $hour.
> *
* @return string */ public function get_hour() { return $this->hour; } /** * Setter for $month.
> *
* @param string $month */ public function set_month($month) { $this->month = $month; } /** * Getter for $month.
> *
* @return string */ public function get_month() { return $this->month; } /** * Setter for $day.
> *
* @param string $day */ public function set_day($day) { $this->day = $day; } /** * Getter for $day.
> *
* @return string */ public function get_day() { return $this->day; } /** * Setter for $dayofweek.
> *
* @param string $dayofweek * @param bool $expandr - if true (default) an 'R' value in a time is expanded to an appropriate int. * If false, they are left as 'R' */ public function set_day_of_week($dayofweek, $expandr = true) { if ($dayofweek === 'R' && $expandr) { $dayofweek = mt_rand(self::DAYOFWEEKMIN, self::DAYOFWEEKMAX); } $this->dayofweek = $dayofweek; } /** * Getter for $dayofweek.
> *
* @return string */ public function get_day_of_week() { return $this->dayofweek; } /** * Setter for $disabled.
> *
* @param bool $disabled */ public function set_disabled($disabled) { $this->disabled = (bool)$disabled; } /** * Getter for $disabled. * @return bool */ public function get_disabled() { return $this->disabled; } /** * Override this function if you want this scheduled task to run, even if the component is disabled. * * @return bool */ public function get_run_if_component_disabled() { return false; } /**
> * Informs whether the given field is valid. * Take a cron field definition and return an array of valid numbers with the range min-max. > * Use the constants FIELD_* to identify the field. * > * Have to be called after the method set_{field}(string). * @param string $field - The field definition. > * * @param int $min - The minimum allowable value. > * @param string $field field identifier; expected values from constants FIELD_*. * @param int $max - The maximum allowable value. > * * @return array(int) > * @return bool true if given field is valid. false otherwise. */ > */ public function eval_cron_field($field, $min, $max) { > public function is_valid(string $field): bool { // Cleanse the input. > return !empty($this->get_valid($field)); $field = trim($field); > } > // Format for a field is: > /** // <fieldlist> := <range>(/<step>)(,<fieldlist>) > * Calculates the list of valid values according to the given field and stored expression. // <step> := int > * // <range> := <any>|<int>|<min-max> > * @param string $field field identifier. Must be one of those FIELD_*. // <any> := * > * // <min-max> := int-int > * @return array(int) list of matching values. // End of format BNF. > * > * @throws \coding_exception when passed an invalid field identifier. // This function is complicated but is covered by unit tests. > */ $range = array(); > private function get_valid(string $field): array { > switch($field) { $matches = array(); > case self::FIELD_MINUTE: preg_match_all('@[0-9]+|\*|,|/|-@', $field, $matches); > $min = self::MINUTEMIN; > $max = self::MINUTEMAX; $last = 0; > break; $inrange = false; > case self::FIELD_HOUR: $instep = false; > $min = self::HOURMIN; > $max = self::HOURMAX; foreach ($matches[0] as $match) { > break; if ($match == '*') { > case self::FIELD_DAY: array_push($range, range($min, $max)); > $min = self::DAYMIN; } else if ($match == '/') { > $max = self::DAYMAX; $instep = true; > break; } else if ($match == '-') { > case self::FIELD_MONTH: $inrange = true; > $min = self::MONTHMIN; } else if (is_numeric($match)) { > $max = self::MONTHMAX; if ($instep) { > break; $i = 0; > case self::FIELD_DAYOFWEEK: for ($i = 0; $i < count($range[count($range) - 1]); $i++) { > $min = self::DAYOFWEEKMIN; if (($i) % $match != 0) { > $max = self::DAYOFWEEKMAXINPUT; $range[count($range) - 1][$i] = -1; > break; } > default: } > throw new \coding_exception("Field '$field' is not a valid crontab identifier."); $inrange = false; > } } else if ($inrange) { > if (count($range)) { > $result = $this->eval_cron_field($this->{$field}, $min, $max); $range[count($range) - 1] = range($last, $match); > if ($field === self::FIELD_DAYOFWEEK) { } > // For day of week, 0 and 7 both mean Sunday; if there is a 7 we set 0. The result array is sorted. $inrange = false; > if (end($result) === 7) { } else { > // Remove last element. if ($match >= $min && $match <= $max) { > array_pop($result); array_push($range, $match); > // Insert 0 as first element if it's not there already. } > if (reset($result) !== 0) { $last = $match; > array_unshift($result, 0); } > } } > } } > } > return $result; // Flatten the result. > } $result = array(); > foreach ($range as $r) { > /**
<
foreach ($r as $rr) {
> if ($min > $match || $match > $max) { if ($rr >= $min && $rr <= $max) { > // This is a value error: The value lays out of the expected range of values. $result[$rr] = 1; > return []; } > }
< $i = 0;
> // Normalise range property, account for "5/10". > $insteprange = $range[count($range) - 1]; > if (!is_array($insteprange)) { > $range[count($range) - 1] = range($insteprange, $max); > }
< $inrange = false;
> $instep = false;
< if ($match >= $min && $match <= $max) {
< }
}
> // If inrange or instep were not processed, there is a syntax error. } > // Cleanup any existing values to show up the error. } > if ($inrange || $instep) { $result = array_keys($result); > return []; sort($result, SORT_NUMERIC); > } return $result; >
} /** * Assuming $list is an ordered list of items, this function returns the item * in the list that is greater than or equal to the current value (or 0). If * no value is greater than or equal, this will return the first valid item in the list. * If list is empty, this function will return 0. * * @param int $current The current value * @param int[] $list The list of valid items. * @return int $next. */ private function next_in_list($current, $list) { foreach ($list as $l) { if ($l >= $current) { return $l; } } if (count($list)) { return $list[0]; } return 0; } /** * Calculate when this task should next be run based on the schedule.
> * * @return int $nextruntime. > * @param int $now Current time, for testing (leave 0 to use default time)
*/
< public function get_next_scheduled_time() { < global $CFG; < < $validminutes = $this->eval_cron_field($this->minute, self::MINUTEMIN, self::MINUTEMAX); < $validhours = $this->eval_cron_field($this->hour, self::HOURMIN, self::HOURMAX);
> public function get_next_scheduled_time(int $now = 0): int { > if (!$now) { > $now = time(); > }
// We need to change to the server timezone before using php date() functions. \core_date::set_default_server_timezone();
< $daysinmonth = date("t"); < $validdays = $this->eval_cron_field($this->day, 1, $daysinmonth); < $validdaysofweek = $this->eval_cron_field($this->dayofweek, 0, 7); < $validmonths = $this->eval_cron_field($this->month, 1, 12); < $nextvalidyear = date('Y'); < < $currentminute = date("i") + 1; < $currenthour = date("H"); < $currentday = date("j"); < $currentmonth = date("n"); < $currentdayofweek = date("w");
> $validminutes = $this->get_valid(self::FIELD_MINUTE); > $validhours = $this->get_valid(self::FIELD_HOUR); > $validdays = $this->get_valid(self::FIELD_DAY); > $validdaysofweek = $this->get_valid(self::FIELD_DAYOFWEEK); > $validmonths = $this->get_valid(self::FIELD_MONTH); > > // If any of the fields contain no valid data then the task will never run. > if (!$validminutes || !$validhours || !$validdays || !$validdaysofweek || !$validmonths) { > return self::NEVER_RUN_TIME; > }
< $nextvalidminute = $this->next_in_list($currentminute, $validminutes); < if ($nextvalidminute < $currentminute) { < $currenthour += 1;
> $result = self::get_next_scheduled_time_inner($now, $validminutes, $validhours, $validdays, $validdaysofweek, $validmonths); > return $result;
}
< $nextvalidhour = $this->next_in_list($currenthour, $validhours); < if ($nextvalidhour < $currenthour) { < $currentdayofweek += 1; < $currentday += 1;
> > /** > * Recursively calculate the next valid time for this task. > * > * @param int $now Start time > * @param array $validminutes Valid minutes > * @param array $validhours Valid hours > * @param array $validdays Valid days > * @param array $validdaysofweek Valid days of week > * @param array $validmonths Valid months > * @param int $originalyear Zero for first call, original year for recursive calls > * @return int Next run time > */ > protected function get_next_scheduled_time_inner(int $now, array $validminutes, array $validhours, > array $validdays, array $validdaysofweek, array $validmonths, int $originalyear = 0) { > $currentyear = (int)date('Y', $now); > if ($originalyear) { > // In recursive calls, check we didn't go more than 8 years ahead, that indicates the > // user has chosen an impossible date. 8 years is the maximum time, considering a task > // set to run on 29 February over a century boundary when a leap year is skipped. > if ($currentyear - $originalyear > 8) { > // Use this time if it's never going to happen. > return self::NEVER_RUN_TIME;
}
< $nextvaliddayofmonth = $this->next_in_list($currentday, $validdays); < $nextvaliddayofweek = $this->next_in_list($currentdayofweek, $validdaysofweek);
> $firstyear = $originalyear; > } else { > $firstyear = $currentyear; > } > $currentmonth = (int)date('n', $now); > > // Evaluate month first. > $nextvalidmonth = $this->next_in_list($currentmonth, $validmonths); > if ($nextvalidmonth < $currentmonth) { > $currentyear += 1; > } > // If we moved to another month, set the current time to start of month, and restart calculations. > if ($nextvalidmonth !== $currentmonth) { > $newtime = strtotime($currentyear . '-' . $nextvalidmonth . '-01 00:00'); > return $this->get_next_scheduled_time_inner($newtime, $validminutes, $validhours, $validdays, > $validdaysofweek, $validmonths, $firstyear); > } > > // Special handling for dayofmonth vs dayofweek (see man 5 cron). If both are specified, then > // it is ok to continue when either matches. If only one is specified then it must match. > $currentday = (int)date("j", $now); > $currentdayofweek = (int)date("w", $now); > $nextvaliddayofmonth = self::next_in_list($currentday, $validdays); > $nextvaliddayofweek = self::next_in_list($currentdayofweek, $validdaysofweek);
$daysincrementbymonth = $nextvaliddayofmonth - $currentday;
> $daysinmonth = (int)date('t', $now);
if ($nextvaliddayofmonth < $currentday) { $daysincrementbymonth += $daysinmonth; } $daysincrementbyweek = $nextvaliddayofweek - $currentdayofweek; if ($nextvaliddayofweek < $currentdayofweek) { $daysincrementbyweek += 7; }
< // Special handling for dayofmonth vs dayofweek: < // if either field is * - use the other field < // otherwise - choose the soonest (see man 5 cron).
if ($this->dayofweek == '*') { $daysincrement = $daysincrementbymonth; } else if ($this->day == '*') { $daysincrement = $daysincrementbyweek; } else { // Take the smaller increment of days by month or week.
< $daysincrement = $daysincrementbymonth; < if ($daysincrementbyweek < $daysincrementbymonth) { < $daysincrement = $daysincrementbyweek;
> $daysincrement = min($daysincrementbymonth, $daysincrementbyweek);
}
> } > // If we moved day, recurse using new start time. > if ($daysincrement != 0) { $nextvaliddayofmonth = $currentday + $daysincrement; > $newtime = strtotime($currentyear . '-' . $currentmonth . '-' . $currentday . if ($nextvaliddayofmonth > $daysinmonth) { > ' 00:00 +' . $daysincrement . ' days'); $currentmonth += 1; > return $this->get_next_scheduled_time_inner($newtime, $validminutes, $validhours, $validdays, $nextvaliddayofmonth -= $daysinmonth; > $validdaysofweek, $validmonths, $firstyear);
< $nextvaliddayofmonth = $currentday + $daysincrement; < if ($nextvaliddayofmonth > $daysinmonth) { < $currentmonth += 1; < $nextvaliddayofmonth -= $daysinmonth;
> $currenthour = (int)date('H', $now); > $nextvalidhour = $this->next_in_list($currenthour, $validhours); > if ($nextvalidhour != $currenthour) { > if ($nextvalidhour < $currenthour) { > $offset = ' +1 day'; > } else { > $offset = ''; > } > $newtime = strtotime($currentyear . '-' . $currentmonth . '-' . $currentday . ' ' . $nextvalidhour . > ':00' . $offset); > return $this->get_next_scheduled_time_inner($newtime, $validminutes, $validhours, $validdays, > $validdaysofweek, $validmonths, $firstyear);
< $nextvalidmonth = $this->next_in_list($currentmonth, $validmonths); < if ($nextvalidmonth < $currentmonth) { < $nextvalidyear += 1;
> // Round time down to an exact minute because we need to use numeric calculations on it now. > // If we construct times based on all the components, it will mess up around DST changes > // (because there are two times with the same representation). > $now = intdiv($now, 60) * 60; > > $currentminute = (int)date('i', $now); > $nextvalidminute = $this->next_in_list($currentminute, $validminutes); > if ($nextvalidminute == $currentminute && !$originalyear) { > // This is not a recursive call so time has not moved on at all yet. We can't use the > // same minute as now because it has already happened, it has to be at least one minute > // later, so update time and retry. > $newtime = $now + 60; > return $this->get_next_scheduled_time_inner($newtime, $validminutes, $validhours, $validdays, > $validdaysofweek, $validmonths, $firstyear);
< // Work out the next valid time. < $nexttime = mktime($nextvalidhour, < $nextvalidminute, < 0, < $nextvalidmonth, < $nextvaliddayofmonth, < $nextvalidyear);
> if ($nextvalidminute < $currentminute) { > // The time is in the next hour so we need to recurse. Don't use strtotime at this > // point because it will mess up around DST changes. > $minutesforward = $nextvalidminute + 60 - $currentminute; > $newtime = $now + $minutesforward * 60; > return $this->get_next_scheduled_time_inner($newtime, $validminutes, $validhours, $validdays, > $validdaysofweek, $validmonths, $firstyear); > }
< return $nexttime;
> // The next valid minute is in the same hour so it must be valid according to all other > // checks and we can finally return it. > return $now + ($nextvalidminute - $currentminute) * 60;
} /**
< * Get a descriptive name for this task (shown to admins).
> * Informs whether this task can be run.
*
< * @return string
> * @return bool true when this task can be run. false otherwise. > */ > public function can_run(): bool { > return $this->is_component_enabled() || $this->get_run_if_component_disabled(); > } > > /** > * Checks whether the component and the task disabled flag enables to run this task. > * This do not checks whether the task manager allows running them or if the > * site allows tasks to "run now". > * > * @return bool true if task is enabled. false otherwise.
*/
< public abstract function get_name();
> public function is_enabled(): bool { > return $this->can_run() && !$this->get_disabled(); > }
> /** } > * Produces a valid id string to use as id attribute based on the given FQCN class name. > * > * @param string $classname FQCN of a task. > * @return string valid string to be used as id attribute. > */ > public static function get_html_id(string $classname): string { > return str_replace('\\', '-', ltrim($classname, '\\')); > }