[Summary view] [Print] [Text view]

   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   * This file contains the backup user interface class
  19   *
  20   * @package   core_backup
  21   * @copyright 2010 Sam Hemelryk
  22   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  /**
  26   * This is the backup user interface class
  27   *
  28   * The backup user interface class manages the user interface and backup for
  29   * Moodle.
  30   *
  31   * @package   core_backup
  32   * @copyright 2010 Sam Hemelryk
  33   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34   */
  35  abstract class base_ui {
  36      /**
  37       * The progress of this instance of the backup ui class
  38       * It is in the initial stage.
  39       */
  40      const PROGRESS_INTIAL = 0;
  41  
  42      /**
  43       * The progress of this instance of the backup ui class
  44       * It is processed.
  45       */
  46      const PROGRESS_PROCESSED = 1;
  47  
  48      /**
  49       * The progress of this instance of the backup ui class
  50       * It is saved.
  51       */
  52      const PROGRESS_SAVED = 2;
  53  
  54      /**
  55       * The progress of this instance of the backup ui class
  56       * It has been executed.
  57       */
  58      const PROGRESS_EXECUTED = 3;
  59  
  60      /**
  61       * The controller
  62       * @var backup_controller|restore_controller
  63       */
  64      protected $controller;
  65  
  66      /**
  67       * The current stage
  68       * @var base_ui_stage
  69       */
  70      protected $stage;
  71  
  72      /**
  73       * The current progress of the UI
  74       * @var int One of self::PROGRESS_*
  75       */
  76      protected $progress;
  77  
  78      /**
  79       * The number of changes made by dependency enforcement
  80       * @var int
  81       */
  82      protected $dependencychanges = 0;
  83  
  84      /**
  85       * Yay for constructors
  86       * @param backup_controller $controller
  87       * @param array $params
  88       */
  89      public function __construct($controller, array $params = null) {
  90          $this->controller = $controller;
  91          $this->progress = self::PROGRESS_INTIAL;
  92          $this->stage = $this->initialise_stage(null, $params);
  93          // Process UI event before to be safe.
  94          $this->controller->process_ui_event();
  95      }
  96  
  97      /**
  98       * Destorys the backup controller and the loaded stage.
  99       */
 100      public function destroy() {
 101  
 102          if ($this->controller) {
 103              $this->controller->destroy();
 104          }
 105          unset($this->stage);
 106  
 107      }
 108  
 109      /**
 110       * Intialises what ever stage is requested. If none are requested we check
 111       * params for 'stage' and default to initial
 112       *
 113       * @param int|null $stage The desired stage to intialise or null for the default
 114       * @param array $params
 115       * @return base_ui_stage
 116       */
 117      abstract protected function initialise_stage($stage = null, array $params = null);
 118  
 119      /**
 120       * This processes the current stage of the backup
 121       * @throws backup_ui_exception
 122       * @return bool
 123       */
 124      public function process() {
 125          if ($this->progress >= self::PROGRESS_PROCESSED) {
 126              throw new backup_ui_exception('backupuialreadyprocessed');
 127          }
 128          $this->progress = self::PROGRESS_PROCESSED;
 129  
 130          if (optional_param('previous', false, PARAM_BOOL) && $this->stage->get_stage() > $this->get_first_stage_id()) {
 131              $this->stage = $this->initialise_stage($this->stage->get_prev_stage(), $this->stage->get_params());
 132              return false;
 133          }
 134  
 135          // Process the stage.
 136          $processoutcome = $this->stage->process();
 137  
 138          if ($processoutcome !== false) {
 139              $this->stage = $this->initialise_stage($this->stage->get_next_stage(), $this->stage->get_params());
 140          }
 141  
 142          // Process UI event after to check changes are valid.
 143          $this->controller->process_ui_event();
 144          return $processoutcome;
 145      }
 146  
 147      /**
 148       * Saves the backup controller.
 149       *
 150       * Once this has been called nothing else can be changed in the controller.
 151       *
 152       * @throws base_ui_exception
 153       * @return bool
 154       */
 155      public function save_controller() {
 156          if ($this->progress >= self::PROGRESS_SAVED) {
 157              throw new base_ui_exception('backupuialreadysaved');
 158          }
 159          $this->progress = self::PROGRESS_SAVED;
 160          // First enforce dependencies.
 161          $this->enforce_dependencies();
 162          // Process UI event after to check any changes are valid.
 163          $this->controller->process_ui_event();
 164          // Save the controller.
 165          $this->controller->save_controller();
 166          return true;
 167      }
 168  
 169      /**
 170       * Displays the UI for the backup!
 171       *
 172       * @throws base_ui_exception
 173       * @param core_backup_renderer $renderer
 174       * @return string HTML code to echo
 175       */
 176      public function display(core_backup_renderer $renderer) {
 177          if ($this->progress < self::PROGRESS_SAVED) {
 178              throw new base_ui_exception('backupsavebeforedisplay');
 179          }
 180          return $this->stage->display($renderer);
 181      }
 182  
 183      /**
 184       * Gets all backup tasks from the controller
 185       * @return array Array of backup_task
 186       */
 187      public function get_tasks() {
 188          $plan = $this->controller->get_plan();
 189          $tasks = $plan->get_tasks();
 190          return $tasks;
 191      }
 192  
 193      /**
 194       * Gets the stage we are on
 195       * @return int
 196       */
 197      public function get_stage() {
 198          return $this->stage->get_stage();
 199      }
 200  
 201      /**
 202       * Gets the name of the stage we are on
 203       * @return string
 204       */
 205      public function get_stage_name() {
 206          return $this->stage->get_name();
 207      }
 208  
 209      /**
 210       * Gets the backup id from the controller
 211       * @return string
 212       */
 213      abstract public function get_uniqueid();
 214  
 215      /**
 216       * Executes the backup plan
 217       * @return bool
 218       */
 219      abstract public function execute();
 220  
 221      /**
 222       * Enforces dependencies on all settings. Call before save
 223       * @return bool True if dependencies were enforced and changes were made
 224       */
 225      protected function enforce_dependencies() {
 226          // Get the plan.
 227          $plan = $this->controller->get_plan();
 228          // Get the tasks as a var so we can iterate by reference.
 229          $tasks = $plan->get_tasks();
 230          $changes = 0;
 231          foreach ($tasks as &$task) {
 232              // Store as a var so we can iterate by reference.
 233              $settings = $task->get_settings();
 234              foreach ($settings as &$setting) {
 235                  // Get all dependencies for iteration by reference.
 236                  $dependencies = $setting->get_dependencies();
 237                  foreach ($dependencies as &$dependency) {
 238                      // Enforce each dependency.
 239                      if ($dependency->enforce()) {
 240                          $changes++;
 241                      }
 242                  }
 243              }
 244          }
 245          // Store the number of settings that changed through enforcement.
 246          $this->dependencychanges = $changes;
 247          return ($changes > 0);
 248      }
 249  
 250      /**
 251       * Returns true if enforce_dependencies changed any settings
 252       * @return bool
 253       */
 254      public function enforce_changed_dependencies() {
 255          return ($this->dependencychanges > 0);
 256      }
 257  
 258      /**
 259       * Loads the backup controller if we are tracking one
 260       * @throws coding_exception
 261       * @param string|bool $uniqueid
 262       * @return backup_controller|false
 263       */
 264      public static function load_controller($uniqueid = false) {
 265          throw new coding_exception('load_controller() method needs to be overridden in each subclass of base_ui');
 266      }
 267  
 268      /**
 269       * Cancels the current backup/restore and redirects the user back to the relevant place
 270       */
 271      public function cancel_process() {
 272          global $PAGE;
 273          // Determine the appropriate URL to redirect the user to.
 274          if ($PAGE->context->contextlevel == CONTEXT_MODULE && $PAGE->cm !== null) {
 275              $relevanturl = new moodle_url('/mod/'.$PAGE->cm->modname.'/view.php', array('id' => $PAGE->cm->id));
 276          } else {
 277              $relevanturl = new moodle_url('/course/view.php', array('id' => $PAGE->course->id));
 278          }
 279          redirect($relevanturl);
 280      }
 281  
 282      /**
 283       * Gets an array of progress bar items that can be displayed through the backup renderer.
 284       * @return array Array of items for the progress bar
 285       */
 286      abstract public function get_progress_bar();
 287      /**
 288       * Gets the format for the backup
 289       * @return int
 290       */
 291      public function get_format() {
 292          return $this->controller->get_format();
 293      }
 294      /**
 295       * Gets the type of the backup
 296       * @return int
 297       */
 298      public function get_type() {
 299          return $this->controller->get_type();
 300      }
 301  
 302      /**
 303       * Returns the controller object.
 304       * @return backup_controller|restore_controller
 305       */
 306      public function get_controller() {
 307          return $this->controller;
 308      }
 309      /**
 310       * Gets the ID used in creating the controller. Relates to course/section/cm
 311       * @return int
 312       */
 313      public function get_controller_id() {
 314          return $this->controller->get_id();
 315      }
 316      /**
 317       * Gets the requested setting
 318       * @param string $name
 319       * @param bool $default
 320       * @return mixed
 321       */
 322      public function get_setting($name, $default = false) {
 323          try {
 324              return $this->controller->get_plan()->get_setting($name);
 325          } catch (Exception $e) {
 326              debugging('Failed to find the setting: '.$name, DEBUG_DEVELOPER);
 327              return $default;
 328          }
 329      }
 330      /**
 331       * Gets the value for the requested setting
 332       *
 333       * @param string $name
 334       * @param bool $default
 335       * @return mixed
 336       */
 337      public function get_setting_value($name, $default = false) {
 338          try {
 339              return $this->controller->get_plan()->get_setting($name)->get_value();
 340          } catch (Exception $e) {
 341              debugging('Failed to find the setting: '.$name, DEBUG_DEVELOPER);
 342              return $default;
 343          }
 344      }
 345  
 346      /**
 347       * Returns the name of this stage.
 348       * @return mixed
 349       */
 350      abstract public function get_name();
 351  
 352      /**
 353       * Returns the first stage ID.
 354       * @return mixed
 355       */
 356      abstract public function get_first_stage_id();
 357  }
 358  
 359  /**
 360   * Backup user interface exception. Modelled off the backup_exception class
 361   *
 362   * @package   core_backup
 363   * @copyright 2010 Sam Hemelryk
 364   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 365   */
 366  class base_ui_exception extends backup_exception {}