Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.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/>.

/**
 * @package moodlecore
 * @subpackage backup-plan
 * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

/**
 * Abstract class defining the basis for one execution (backup/restore) task
 *
 * TODO: Finish phpdocs
 */
abstract class base_task implements checksumable, executable, loggable {

> /** @var string */
protected $name; // One simple name for identification purposes
> /** @var backup_plan|restore_plan */
protected $plan; // Plan this is part of
> /** @var base_setting[] */
protected $settings; // One array of base_setting elements to define this task
> /** @var base_step[] */
protected $steps; // One array of base_step elements
<
> /** @var bool */
protected $built; // Flag to know if one task has been built
> /** @var bool */
protected $executed; // Flag to know if one task has been executed /** * Constructor - instantiates one object of this class */ public function __construct($name, $plan = null) { if (!is_null($plan) && !($plan instanceof base_plan)) { throw new base_task_exception('wrong_base_plan_specified'); } $this->name = $name; $this->plan = $plan; $this->settings = array(); $this->steps = array(); $this->built = false; $this->executed = false; if (!is_null($plan)) { // Add the task to the plan if specified $plan->add_task($this); } } public function get_name() { return $this->name; } public function get_steps() { return $this->steps; } public function get_settings() { return $this->settings; } /** * Returns the weight of this task, an approximation of the amount of time * it will take. By default this value is 1. It can be increased for longer * tasks. * * @return int Weight */ public function get_weight() { return 1; } public function get_setting($name) { // First look in task settings $result = null; foreach ($this->settings as $key => $setting) { if ($setting->get_name() == $name) { if ($result != null) { throw new base_task_exception('multiple_settings_by_name_found', $name); } else { $result = $setting; } } } if ($result) { return $result; } else { // Fallback to plan settings return $this->plan->get_setting($name); } } public function setting_exists($name) { return $this->plan->setting_exists($name); } public function get_setting_value($name) { return $this->get_setting($name)->get_value(); } public function get_courseid() { return $this->plan->get_courseid(); } public function get_basepath() { return $this->plan->get_basepath(); } public function get_taskbasepath() { return $this->get_basepath(); } public function get_logger() { return $this->plan->get_logger(); } /** * Gets the progress reporter, which can be used to report progress within * the backup or restore process. * * @return \core\progress\base Progress reporting object */ public function get_progress() { return $this->plan->get_progress(); } public function log($message, $level, $a = null, $depth = null, $display = false) { backup_helper::log($message, $level, $a, $depth, $display, $this->get_logger()); } public function add_step($step) { if (! $step instanceof base_step) { throw new base_task_exception('wrong_base_step_specified'); } // link the step with the task $step->set_task($this); $this->steps[] = $step; } public function set_plan($plan) { if (! $plan instanceof base_plan) { throw new base_task_exception('wrong_base_plan_specified'); } $this->plan = $plan; $this->define_settings(); // Settings are defined when plan & task are linked } /** * Function responsible for building the steps of any task * (must set the $built property to true) */ public abstract function build(); /** * Function responsible for executing the steps of any task * (setting the $executed property to true) */ public function execute() { if (!$this->built) { throw new base_task_exception('base_task_not_built', $this->name); } if ($this->executed) { throw new base_task_exception('base_task_already_executed', $this->name); } // Starts progress based on the weight of this task and number of steps. $progress = $this->get_progress(); $progress->start_progress($this->get_name(), count($this->steps), $this->get_weight()); $done = 0; // Execute all steps. foreach ($this->steps as $step) { $result = $step->execute(); // If step returns array, it will be forwarded to plan // (TODO: shouldn't be array but proper result object) if (is_array($result) and !empty($result)) { $this->add_result($result); } $done++; $progress->progress($done); } // Mark as executed if any step has been executed if (!empty($this->steps)) { $this->executed = true; } // Finish progress for this task. $progress->end_progress(); } /** * Destroy all circular references. It helps PHP 5.2 a lot! */ public function destroy() { // Before reseting anything, call destroy recursively foreach ($this->steps as $step) { $step->destroy(); } foreach ($this->settings as $setting) { $setting->destroy(); } // Everything has been destroyed recursively, now we can reset safely $this->steps = array(); $this->settings = array(); $this->plan = null; } public function is_checksum_correct($checksum) { return $this->calculate_checksum() === $checksum; } public function calculate_checksum() { // Let's do it using name and settings and steps return md5($this->name . '-' . backup_general_helper::array_checksum_recursive($this->settings) . backup_general_helper::array_checksum_recursive($this->steps)); } /** * Add the given info to the current plan's results. * * @see base_plan::add_result() * @param array $result associative array describing a result of a task/step */ public function add_result($result) { if (!is_null($this->plan)) { $this->plan->add_result($result); } else { debugging('Attempting to add a result of a task not binded with a plan', DEBUG_DEVELOPER); } } /** * Return the current plan's results * * @return array|null */ public function get_results() { if (!is_null($this->plan)) { return $this->plan->get_results(); } else { debugging('Attempting to get results of a task not binded with a plan', DEBUG_DEVELOPER); return null; } } // Protected API starts here /** * This function is invoked on activity creation in order to add all the settings * that are associated with one task. The function will, directly, inject the settings * in the task. */ protected abstract function define_settings(); protected function add_setting($setting) { if (! $setting instanceof base_setting) { throw new base_setting_exception('wrong_base_setting_specified'); } $this->settings[] = $setting; } } /* * Exception class used by all the @base_task stuff */ class base_task_exception extends moodle_exception { public function __construct($errorcode, $a=NULL, $debuginfo=null) { parent::__construct($errorcode, '', '', $a, $debuginfo); } }