[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  // This file is part of Moodle - http://moodle.org/
   4  //
   5  // Moodle is free software: you can redistribute it and/or modify
   6  // it under the terms of the GNU General Public License as published by
   7  // the Free Software Foundation, either version 3 of the License, or
   8  // (at your option) any later version.
   9  //
  10  // Moodle is distributed in the hope that it will be useful,
  11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  // GNU General Public License for more details.
  14  //
  15  // You should have received a copy of the GNU General Public License
  16  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17  
  18  /**
  19   * Defines restore_plugin class
  20   *
  21   * @package     core_backup
  22   * @subpackage  moodle2
  23   * @category    backup
  24   * @copyright   2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  25   * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  26   */
  27  
  28  defined('MOODLE_INTERNAL') || die();
  29  
  30  /**
  31   * Class implementing the plugins support for moodle2 restore
  32   *
  33   * TODO: Finish phpdocs
  34   */
  35  abstract class restore_plugin {
  36  
  37      protected $plugintype;
  38      protected $pluginname;
  39      protected $connectionpoint;
  40      protected $step;
  41      protected $task;
  42  
  43      public function __construct($plugintype, $pluginname, $step) {
  44          $this->plugintype = $plugintype;
  45          $this->pluginname = $pluginname;
  46          $this->step          = $step;
  47          $this->task          = $step->get_task();
  48          $this->connectionpoint = '';
  49      }
  50  
  51      public function define_plugin_structure($connectionpoint) {
  52          if (!$connectionpoint instanceof restore_path_element) {
  53              throw new restore_step_exception('restore_path_element_required', $connectionpoint);
  54          }
  55  
  56          $paths = array();
  57          $this->connectionpoint = $connectionpoint;
  58          $methodname = 'define_' . basename($this->connectionpoint->get_path()) . '_plugin_structure';
  59  
  60          if (method_exists($this, $methodname)) {
  61              if ($bluginpaths = $this->$methodname()) {
  62                  foreach ($bluginpaths as $path) {
  63                      $path->set_processing_object($this);
  64                      $paths[] = $path;
  65                  }
  66              }
  67          }
  68          return $paths;
  69      }
  70  
  71      /**
  72       * after_execute dispatcher for any restore_plugin class
  73       *
  74       * This method will dispatch execution to the corresponding
  75       * after_execute_xxx() method when available, with xxx
  76       * being the connection point of the instance, so plugin
  77       * classes with multiple connection points will support
  78       * multiple after_execute methods, one for each connection point
  79       */
  80      public function launch_after_execute_methods() {
  81          // Check if the after_execute method exists and launch it
  82          $afterexecute = 'after_execute_' . basename($this->connectionpoint->get_path());
  83          if (method_exists($this, $afterexecute)) {
  84              $this->$afterexecute();
  85          }
  86      }
  87  
  88      /**
  89       * after_restore dispatcher for any restore_plugin class
  90       *
  91       * This method will dispatch execution to the corresponding
  92       * after_restore_xxx() method when available, with xxx
  93       * being the connection point of the instance, so plugin
  94       * classes with multiple connection points will support
  95       * multiple after_restore methods, one for each connection point
  96       */
  97      public function launch_after_restore_methods() {
  98          // Check if the after_restore method exists and launch it
  99          $afterrestore = 'after_restore_' . basename($this->connectionpoint->get_path());
 100          if (method_exists($this, $afterrestore)) {
 101              $this->$afterrestore();
 102          }
 103      }
 104  
 105      /**
 106       * Returns one array with all the decode contents
 107       * to be processed by the links decoder
 108       *
 109       * This method, given one plugin type, returns one
 110       * array of {@link restore_decode_content} objects
 111       * that will be added to the restore decoder in order
 112       * to perform modifications under the plugin contents.
 113       *
 114       * The objects are retrieved by calling to the {@link define_decode_contents}
 115       * method (when available), first in the main restore_xxxx_plugin class
 116       * and later on each of the available subclasses
 117       */
 118      static public function get_restore_decode_contents($plugintype) {
 119          $decodecontents = array();
 120          // Check the requested plugintype is a valid one
 121          if (!array_key_exists($plugintype, core_component::get_plugin_types($plugintype))) {
 122               throw new backup_step_exception('incorrect_plugin_type', $plugintype);
 123          }
 124          // Check the base plugin class exists
 125          $classname = 'restore_' . $plugintype . '_plugin';
 126          if (!class_exists($classname)) {
 127               throw new backup_step_exception('plugin_class_not_found', $classname);
 128          }
 129          // First, call to the define_plugin_decode_contents in the base plugin class
 130          // (must exist by design in all the plugin base classes)
 131          if (method_exists($classname, 'define_plugin_decode_contents')) {
 132              $decodecontents = array_merge($decodecontents, call_user_func(array($classname, 'define_plugin_decode_contents')));
 133          }
 134          // Now, iterate over all the possible plugins available
 135          // (only the needed ones have been loaded, so they will
 136          // be the ones being asked here). Fetch their restore contents
 137          // by calling (if exists) to their define_decode_contents() method
 138          $plugins = core_component::get_plugin_list($plugintype);
 139          foreach ($plugins as $plugin => $plugindir) {
 140              $classname = 'restore_' . $plugintype . '_' . $plugin . '_plugin';
 141              if (class_exists($classname)) {
 142                  if (method_exists($classname, 'define_decode_contents')) {
 143                      $decodecontents = array_merge($decodecontents, call_user_func(array($classname, 'define_decode_contents')));
 144                  }
 145              }
 146          }
 147          return $decodecontents;
 148      }
 149  
 150      /**
 151       * Define the contents in the plugin that must be
 152       * processed by the link decoder
 153       */
 154      static public function define_plugin_decode_contents() {
 155          throw new coding_exception('define_plugin_decode_contents() method needs to be overridden in each subclass of restore_plugin');
 156      }
 157  
 158  // Protected API starts here
 159  
 160  // restore_step/structure_step/task wrappers
 161  
 162      protected function get_restoreid() {
 163          if (is_null($this->task)) {
 164              throw new restore_step_exception('not_specified_restore_task');
 165          }
 166          return $this->task->get_restoreid();
 167      }
 168  
 169      /**
 170       * To send ids pairs to backup_ids_table and to store them into paths
 171       *
 172       * This method will send the given itemname and old/new ids to the
 173       * backup_ids_temp table, and, at the same time, will save the new id
 174       * into the corresponding restore_path_element for easier access
 175       * by children. Also will inject the known old context id for the task
 176       * in case it's going to be used for restoring files later
 177       */
 178      protected function set_mapping($itemname, $oldid, $newid, $restorefiles = false, $filesctxid = null, $parentid = null) {
 179          $this->step->set_mapping($itemname, $oldid, $newid, $restorefiles, $filesctxid, $parentid);
 180      }
 181  
 182      /**
 183       * Returns the latest (parent) old id mapped by one pathelement
 184       */
 185      protected function get_old_parentid($itemname) {
 186          return $this->step->get_old_parentid($itemname);
 187      }
 188  
 189      /**
 190       * Returns the latest (parent) new id mapped by one pathelement
 191       */
 192      protected function get_new_parentid($itemname) {
 193          return $this->step->get_new_parentid($itemname);
 194      }
 195  
 196      /**
 197       * Return the new id of a mapping for the given itemname
 198       *
 199       * @param string $itemname the type of item
 200       * @param int $oldid the item ID from the backup
 201       * @param mixed $ifnotfound what to return if $oldid wasnt found. Defaults to false
 202       */
 203      protected function get_mappingid($itemname, $oldid, $ifnotfound = false) {
 204          return $this->step->get_mappingid($itemname, $oldid, $ifnotfound);
 205      }
 206  
 207      /**
 208       * Return the complete mapping from the given itemname, itemid
 209       */
 210      protected function get_mapping($itemname, $oldid) {
 211          return $this->step->get_mapping($itemname, $oldid);
 212      }
 213  
 214      /**
 215       * Add all the existing file, given their component and filearea and one backup_ids itemname to match with
 216       */
 217      protected function add_related_files($component, $filearea, $mappingitemname, $filesctxid = null, $olditemid = null) {
 218          $this->step->add_related_files($component, $filearea, $mappingitemname, $filesctxid, $olditemid);
 219      }
 220  
 221      /**
 222       * Apply course startdate offset based in original course startdate and course_offset_startdate setting
 223       * Note we are using one static cache here, but *by restoreid*, so it's ok for concurrence/multiple
 224       * executions in the same request
 225       */
 226      protected function apply_date_offset($value) {
 227          return $this->step->apply_date_offset($value);
 228      }
 229  
 230      /**
 231       * Returns the value of one (task/plan) setting
 232       */
 233      protected function get_setting_value($name) {
 234          if (is_null($this->task)) {
 235              throw new restore_step_exception('not_specified_restore_task');
 236          }
 237          return $this->task->get_setting_value($name);
 238      }
 239  
 240  // end of restore_step/structure_step/task wrappers
 241  
 242      /**
 243       * Simple helper function that returns the name for the restore_path_element
 244       * It's not mandatory to use it but recommended ;-)
 245       */
 246      protected function get_namefor($name = '') {
 247          $name = $name !== '' ? '_' . $name : '';
 248          return $this->plugintype . '_' . $this->pluginname . $name;
 249      }
 250  
 251      /**
 252       * Simple helper function that returns the base (prefix) of the path for the restore_path_element
 253       * Useful if we used get_recommended_name() in backup. It's not mandatory to use it but recommended ;-)
 254       */
 255      protected function get_pathfor($path = '') {
 256          $path = trim($path, '/') !== '' ? '/' . trim($path, '/') : '';
 257          return $this->connectionpoint->get_path() . '/' .
 258                 'plugin_' . $this->plugintype . '_' .
 259                 $this->pluginname . '_' . basename($this->connectionpoint->get_path()) . $path;
 260      }
 261  }