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 = '*';
> /** > * Minute field identifier. /** @var string $day - Pattern to work out the valid days */ > */ private $day = '*'; > const FIELD_MINUTE = 'minute'; > /** /** @var string $month - Pattern to work out the valid months */ > * Hour field identifier. private $month = '*'; > */ > const FIELD_HOUR = 'hour'; /** @var string $dayofweek - Pattern to work out the valid dayofweek */ > /** private $dayofweek = '*'; > * Day-of-month field identifier. > */ /** @var int $lastruntime - When this task was last run */ > const FIELD_DAY = 'day'; private $lastruntime = 0; > /** > * Month field identifier. /** @var boolean $customised - Has this task been changed from it's default schedule? */ > */ private $customised = false; > const FIELD_MONTH = 'month'; > /** /** @var boolean $overridden - Does the task have values set VIA config? */ > * Day-of-week field identifier. private $overridden = false; > */ > const FIELD_DAYOFWEEK = 'dayofweek'; /** @var int $disabled - Is this task disabled in cron? */ >
private $disabled = false; /** * Get the last run time for this scheduled task.
> *
* @return int */ public function get_last_run_time() { return $this->lastruntime; } /** * 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?
> *
* @param bool */ public function set_customised($customised) { $this->customised = $customised; } /** * Has this task been changed from it's default config?
> *
* @return bool */ public function is_overridden(): bool { return $this->overridden; } /** * Set the overridden value.
> *
* @param bool $overridden */ public function set_overridden(bool $overridden): void { $this->overridden = $overridden; } /** * Setter for $minute. Accepts a special 'R' value * which will be translated to a random minute.
> *
* @param string $minute * @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_minute($minute, $expandr = true) { if ($minute === 'R' && $expandr) { $minute = mt_rand(self::MINUTEMIN, self::MINUTEMAX); } $this->minute = $minute; } /** * Getter for $minute.
> *
* @return string */ public function get_minute() { return $this->minute; } /** * Setter for $hour. Accepts a special 'R' value * which will be translated to a random hour.
> *
* @param string $hour * @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_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::DAYOFWEEKMAX; $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)) { > return $this->eval_cron_field($this->{$field}, $min, $max); $range[count($range) - 1] = range($last, $match); > } } > $inrange = false; > /**
<
if ($match >= $min && $match <= $max) {
> if ($min > $match || $match > $max) { array_push($range, $match); > // This is a value error: The value lays out of the expected range of values. } > return []; $last = $match; > }
< $i = 0;
< $inrange = false;
> $instep = false;
< if ($match >= $min && $match <= $max) {
< }
// Flatten the result.
> // If inrange or instep were not processed, there is a syntax error. $result = array(); > // Cleanup any existing values to show up the error. foreach ($range as $r) { > if ($inrange || $instep) { if (is_array($r)) { > return []; foreach ($r as $rr) { > } if ($rr >= $min && $rr <= $max) { >
$result[$rr] = 1; } } } else if (is_numeric($r)) { if ($r >= $min && $r <= $max) { $result[$r] = 1; } } } $result = array_keys($result); 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. */ 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); <
// 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);
> $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); >
$nextvalidyear = date('Y'); $currentminute = date("i") + 1; $currenthour = date("H"); $currentday = date("j"); $currentmonth = date("n"); $currentdayofweek = date("w"); $nextvalidminute = $this->next_in_list($currentminute, $validminutes); if ($nextvalidminute < $currentminute) { $currenthour += 1; } $nextvalidhour = $this->next_in_list($currenthour, $validhours); if ($nextvalidhour < $currenthour) { $currentdayofweek += 1; $currentday += 1; } $nextvaliddayofmonth = $this->next_in_list($currentday, $validdays); $nextvaliddayofweek = $this->next_in_list($currentdayofweek, $validdaysofweek); $daysincrementbymonth = $nextvaliddayofmonth - $currentday;
> $daysinmonth = date('t');
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; } } $nextvaliddayofmonth = $currentday + $daysincrement; if ($nextvaliddayofmonth > $daysinmonth) { $currentmonth += 1; $nextvaliddayofmonth -= $daysinmonth; } $nextvalidmonth = $this->next_in_list($currentmonth, $validmonths); if ($nextvalidmonth < $currentmonth) { $nextvalidyear += 1; } // Work out the next valid time. $nexttime = mktime($nextvalidhour, $nextvalidminute, 0, $nextvalidmonth, $nextvaliddayofmonth, $nextvalidyear); return $nexttime; } /**
> * Informs whether this task can be run. * Get a descriptive name for this task (shown to admins). > * * > * @return bool true when this task can be run. false otherwise. * @return string > */ */ > public function can_run(): bool { public abstract function get_name(); > 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 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, '\\')); > } > > /**
< public abstract function get_name();
> abstract public function get_name();