[Summary view]

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

   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  /**
  19   * External backup API.
  20   *
  21   * @package    core_backup
  22   * @category   external
  23   * @copyright  2018 Matt Porritt <mattp@catalyst-au.net>
  24   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once("$CFG->libdir/externallib.php");
  30  require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
  31  require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php');
  32  
  33  /**
  34   * Backup external functions.
  35   *
  36   * @package    core_backup
  37   * @category   external
  38   * @copyright  2018 Matt Porritt <mattp@catalyst-au.net>
  39   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  40   * @since Moodle 3.7
  41   */
  42  class core_backup_external extends external_api {
  43  
  44      /**
  45       * Returns description of method parameters
  46       *
  47       * @return external_function_parameters
  48       * @since Moodle 3.7
  49       */
  50      public static function get_async_backup_progress_parameters() {
  51          return new external_function_parameters(
  52              array(
  53                  'backupids' => new external_multiple_structure(
  54                          new external_value(PARAM_ALPHANUM, 'Backup id to get progress for', VALUE_REQUIRED, null, NULL_ALLOWED),
  55                          'Backup id to get progress for', VALUE_REQUIRED
  56                   ),
  57                  'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
  58              )
  59          );
  60      }
  61  
  62      /**
  63       * Get asynchronous backup progress.
  64       *
  65       * @param string $backupids The ids of the backup to get progress for.
  66       * @param int $contextid The context the backup relates to.
  67       * @return array $results The array of results.
  68       * @since Moodle 3.7
  69       */
  70      public static function get_async_backup_progress($backupids, $contextid) {
  71          // Release session lock.
  72          \core\session\manager::write_close();
  73  
  74          // Parameter validation.
  75          self::validate_parameters(
  76                  self::get_async_backup_progress_parameters(),
  77                  array(
  78                      'backupids' => $backupids,
  79                      'contextid' => $contextid
  80                  )
  81          );
  82  
  83          // Context validation.
  84          list($context, $course, $cm) = get_context_info_array($contextid);
  85          self::validate_context($context);
  86  
  87          if ($cm) {
  88              require_capability('moodle/backup:backupactivity', $context);
  89          } else {
  90              require_capability('moodle/backup:backupcourse', $context);
  91          }
  92  
  93          $results = array();
  94          foreach ($backupids as $backupid) {
  95              $results[] = backup_controller_dbops::get_progress($backupid);
  96          }
  97  
  98          return $results;
  99      }
 100  
 101      /**
 102       * Returns description of method result value
 103       *
 104       * @return external_description
 105       * @since Moodle 3.7
 106       */
 107      public static function get_async_backup_progress_returns() {
 108          return new external_multiple_structure(
 109              new external_single_structure(
 110                  array(
 111                      'status'   => new external_value(PARAM_INT, 'Backup Status'),
 112                      'progress' => new external_value(PARAM_FLOAT, 'Backup progress'),
 113                      'backupid' => new external_value(PARAM_ALPHANUM, 'Backup id'),
 114                      'operation' => new external_value(PARAM_ALPHANUM, 'operation type'),
 115                  ), 'Backup completion status'
 116            ), 'Backup data'
 117          );
 118      }
 119  
 120      /**
 121       * Returns description of method parameters
 122       *
 123       * @return external_function_parameters
 124       * @since Moodle 3.7
 125       */
 126      public static function get_async_backup_links_backup_parameters() {
 127          return new external_function_parameters(
 128                  array(
 129                      'filename' => new external_value(PARAM_FILE, 'Backup filename', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 130                      'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 131                      'backupid' => new external_value(PARAM_ALPHANUMEXT, 'Backup id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 132                  )
 133           );
 134      }
 135  
 136      /**
 137       * Get the data to be used when generating the table row for an asynchronous backup,
 138       * the table row updates via ajax when backup is complete.
 139       *
 140       * @param string $filename The file name of the backup file.
 141       * @param int $contextid The context the backup relates to.
 142       * @param string $backupid The backup ID to get the backup settings.
 143       * @since Moodle 3.7
 144       */
 145      public static function get_async_backup_links_backup($filename, $contextid, $backupid) {
 146          // Release session lock.
 147          \core\session\manager::write_close();
 148  
 149          // Parameter validation.
 150          self::validate_parameters(
 151                  self::get_async_backup_links_backup_parameters(),
 152                      array(
 153                          'filename' => $filename,
 154                          'contextid' => $contextid,
 155                          'backupid' => $backupid,
 156                      )
 157                  );
 158  
 159          // Context validation.
 160          list($context, $course, $cm) = get_context_info_array($contextid);
 161          self::validate_context($context);
 162          require_capability('moodle/backup:backupcourse', $context);
 163  
 164          // Backups without user info or with the anonymise functionality enabled are sent
 165          // to user's "user_backup" file area.
 166          $filearea = 'backup';
 167          // Get useful info to render async status in correct area.
 168          $bc = \backup_controller::load_controller($backupid);
 169          list($hasusers, $isannon) = \async_helper::get_userdata_backup_settings($bc);
 170          if ($hasusers && !$isannon) {
 171              if ($cm) {
 172                  $filearea = 'activity';
 173              } else {
 174                  $filearea = 'course';
 175              }
 176          }
 177  
 178          $results = \async_helper::get_backup_file_info($filename, $filearea, $contextid);
 179  
 180          return $results;
 181      }
 182  
 183      /**
 184       * Returns description of method result value.
 185       *
 186       * @return external_description
 187       * @since Moodle 3.7
 188       */
 189      public static function get_async_backup_links_backup_returns() {
 190          return new external_single_structure(
 191              array(
 192                 'filesize'   => new external_value(PARAM_TEXT, 'Backup file size'),
 193                 'fileurl' => new external_value(PARAM_URL, 'Backup file URL'),
 194                 'restoreurl' => new external_value(PARAM_URL, 'Backup restore URL'),
 195          ), 'Table row data.');
 196      }
 197      /**
 198       * Returns description of method parameters
 199       *
 200       * @return external_function_parameters
 201       * @since Moodle 3.7
 202       */
 203      public static function get_async_backup_links_restore_parameters() {
 204          return new external_function_parameters(
 205                  array(
 206                      'backupid' => new external_value(PARAM_ALPHANUMEXT, 'Backup id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 207                      'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 208                  )
 209          );
 210      }
 211  
 212      /**
 213       * Get the data to be used when generating the table row for an asynchronous restore,
 214       * the table row updates via ajax when restore is complete.
 215       *
 216       * @param string $backupid The id of the backup record.
 217       * @param int $contextid The context the restore relates to.
 218       * @return array $results The array of results.
 219       * @since Moodle 3.7
 220       */
 221      public static function get_async_backup_links_restore($backupid, $contextid) {
 222          // Release session lock.
 223          \core\session\manager::write_close();
 224  
 225          // Parameter validation.
 226          self::validate_parameters(
 227                  self::get_async_backup_links_restore_parameters(),
 228                      array(
 229                          'backupid' => $backupid,
 230                          'contextid' => $contextid
 231                      )
 232                  );
 233  
 234          // Context validation.
 235          if ($contextid == 0) {
 236              $copyrec = \async_helper::get_backup_record($backupid);
 237              $context = context_course::instance($copyrec->itemid);
 238          } else {
 239              $context = context::instance_by_id($contextid);
 240          }
 241          self::validate_context($context);
 242          require_capability('moodle/restore:restorecourse', $context);
 243  
 244          $results = \async_helper::get_restore_url($backupid);
 245  
 246          return $results;
 247      }
 248  
 249      /**
 250       * Returns description of method result value.
 251       *
 252       * @return external_description
 253       * @since Moodle 3.7
 254       */
 255      public static function get_async_backup_links_restore_returns() {
 256          return new external_single_structure(
 257                  array(
 258                      'restoreurl' => new external_value(PARAM_URL, 'Restore url'),
 259                  ), 'Table row data.');
 260      }
 261  
 262      /**
 263       * Returns description of method parameters
 264       *
 265       * @return external_function_parameters
 266       * @since Moodle 3.9
 267       */
 268      public static function get_copy_progress_parameters() {
 269          return new external_function_parameters(
 270              array(
 271                  'copies' => new external_multiple_structure(
 272                      new external_single_structure(
 273                          array(
 274                              'backupid' => new external_value(PARAM_ALPHANUM, 'Backup id'),
 275                              'restoreid' => new external_value(PARAM_ALPHANUM, 'Restore id'),
 276                              'operation' => new external_value(PARAM_ALPHANUM, 'Operation type'),
 277                          ), 'Copy data'
 278                      ), 'Copy data'
 279                  ),
 280              )
 281          );
 282      }
 283  
 284      /**
 285       * Get the data to be used when generating the table row for a course copy,
 286       * the table row updates via ajax when copy is complete.
 287       *
 288       * @param array $copies Array of ids.
 289       * @return array $results The array of results.
 290       * @since Moodle 3.9
 291       */
 292      public static function get_copy_progress($copies) {
 293          // Release session lock.
 294          \core\session\manager::write_close();
 295  
 296          // Parameter validation.
 297          self::validate_parameters(
 298              self::get_copy_progress_parameters(),
 299              array('copies' => $copies)
 300              );
 301  
 302          $results = array();
 303  
 304          foreach ($copies as $copy) {
 305  
 306              if ($copy['operation'] == \backup::OPERATION_BACKUP) {
 307                  $copyid = $copy['backupid'];
 308              } else {
 309                  $copyid = $copy['restoreid'];
 310              }
 311  
 312              $copyrec = \async_helper::get_backup_record($copyid);
 313              $context = context_course::instance($copyrec->itemid);
 314              self::validate_context($context);
 315  
 316              $copycaps = \core_course\management\helper::get_course_copy_capabilities();
 317              require_all_capabilities($copycaps, $context);
 318  
 319              if ($copy['operation'] == \backup::OPERATION_BACKUP) {
 320                  $result = \backup_controller_dbops::get_progress($copyid);
 321                  if ($result['status'] == \backup::STATUS_FINISHED_OK) {
 322                      $copyid = $copy['restoreid'];
 323                  }
 324              }
 325  
 326              $results[] = \backup_controller_dbops::get_progress($copyid);
 327          }
 328  
 329          return $results;
 330      }
 331  
 332      /**
 333       * Returns description of method result value.
 334       *
 335       * @return external_description
 336       * @since Moodle 3.9
 337       */
 338      public static function get_copy_progress_returns() {
 339          return new external_multiple_structure(
 340              new external_single_structure(
 341                  array(
 342                      'status'   => new external_value(PARAM_INT, 'Copy Status'),
 343                      'progress' => new external_value(PARAM_FLOAT, 'Copy progress'),
 344                      'backupid' => new external_value(PARAM_ALPHANUM, 'Copy id'),
 345                      'operation' => new external_value(PARAM_ALPHANUM, 'Operation type'),
 346                  ), 'Copy completion status'
 347              ), 'Copy data'
 348          );
 349      }
 350  
 351      /**
 352       * Returns description of method parameters
 353       *
 354       * @return external_function_parameters
 355       * @since Moodle 3.9
 356       */
 357      public static function submit_copy_form_parameters() {
 358          return new external_function_parameters(
 359              array(
 360                  'jsonformdata' => new external_value(PARAM_RAW, 'The data from the create copy form, encoded as a json array')
 361              )
 362          );
 363      }
 364  
 365      /**
 366       * Submit the course group form.
 367       *
 368       * @param string $jsonformdata The data from the form, encoded as a json array.
 369       * @return int new group id.
 370       */
 371      public static function submit_copy_form($jsonformdata) {
 372  
 373          // Release session lock.
 374          \core\session\manager::write_close();
 375  
 376          // We always must pass webservice params through validate_parameters.
 377          $params = self::validate_parameters(
 378              self::submit_copy_form_parameters(),
 379              array('jsonformdata' => $jsonformdata)
 380              );
 381  
 382          $formdata = json_decode($params['jsonformdata']);
 383  
 384          $data = array();
 385          parse_str($formdata, $data);
 386  
 387          $context = context_course::instance($data['courseid']);
 388          self::validate_context($context);
 389          $copycaps = \core_course\management\helper::get_course_copy_capabilities();
 390          require_all_capabilities($copycaps, $context);
 391  
 392          // Submit the form data.
 393          $course = get_course($data['courseid']);
 394          $mform = new \core_backup\output\copy_form(
 395              null,
 396              array('course' => $course, 'returnto' => '', 'returnurl' => ''),
 397              'post', '', ['class' => 'ignoredirty'], true, $data);
 398          $mdata = $mform->get_data();
 399  
 400          if ($mdata) {
 401              // Create the copy task.
 402              $copydata = \copy_helper::process_formdata($mdata);
 403              $copyids = \copy_helper::create_copy($copydata);
 404          } else {
 405              throw new moodle_exception('copyformfail', 'backup');
 406          }
 407  
 408          return json_encode($copyids);
 409      }
 410  
 411      /**
 412       * Returns description of method result value.
 413       *
 414       * @return external_description
 415       * @since Moodle 3.9
 416       */
 417      public static function submit_copy_form_returns() {
 418          return new external_value(PARAM_RAW, 'JSON response.');
 419      }
 420  }