backup/externallib.php

   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
  32 /**
  33  * Backup external functions.
  34  *
  35  * @package    core_backup
  36  * @category   external
  37  * @copyright  2018 Matt Porritt <mattp@catalyst-au.net>
  38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39  * @since Moodle 3.7
  40  */
  41 class core_backup_external extends external_api {
  42
  43     /**
  44      * Returns description of method parameters
  45      *
  46      * @return external_function_parameters
  47      * @since Moodle 3.7
  48      */
  49     public static function get_async_backup_progress_parameters() {
  50         return new external_function_parameters(
  51             array(
  52                 'backupids' => new external_multiple_structure(
  53                         new external_value(PARAM_ALPHANUM, 'Backup id to get progress for', VALUE_REQUIRED, null, NULL_ALLOWED),
  54                         'Backup id to get progress for', VALUE_REQUIRED
  55                  ),
  56                 'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
  57             )
  58         );
  59     }
  60
  61     /**
  62      * Get asynchronous backup progress.
  63      *
  64      * @param string $backupids The ids of the backup to get progress for.
  65      * @param int $contextid The context the backup relates to.
  66      * @return array $results The array of results.
  67      * @since Moodle 3.7
  68      */
  69     public static function get_async_backup_progress($backupids, $contextid) {
  70         global $CFG;
  71         require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
  72         require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php');
  73
  74         // Release session lock.
  75         \core\session\manager::write_close();
  76
  77         // Parameter validation.
  78         self::validate_parameters(
  79                 self::get_async_backup_progress_parameters(),
  80                 array(
  81                     'backupids' => $backupids,
  82                     'contextid' => $contextid
  83                 )
  84         );
  85
  86         // Context validation.
  87         list($context, $course, $cm) = get_context_info_array($contextid);
  88         self::validate_context($context);
  89
  90         if ($cm) {
  91             require_capability('moodle/backup:backupactivity', $context);
  92         } else {
  93             require_capability('moodle/backup:backupcourse', $context);
  94             $instanceid = $course->id;
  95         }
  96
  97         $results = array();
  98         foreach ($backupids as $backupid) {
  99             $results[] = backup_controller_dbops::get_progress($backupid);
 100         }
 101
 102         return $results;
 103     }
 104
 105     /**
 106      * Returns description of method result value
 107      *
 108      * @return external_description
 109      * @since Moodle 3.7
 110      */
 111     public static function get_async_backup_progress_returns() {
 112         return new external_multiple_structure(
 113             new external_single_structure(
 114                 array(
 115                     'status'   => new external_value(PARAM_INT, 'Backup Status'),
 116                     'progress' => new external_value(PARAM_FLOAT, 'Backup progress'),
 117                     'backupid' => new external_value(PARAM_ALPHANUM, 'Backup id'),
 118                     'operation' => new external_value(PARAM_ALPHANUM, 'operation type'),
 119                 ), 'Backup completion status'
 120           ), 'Backup data'
 121         );
 122     }
 123
 124     /**
 125      * Returns description of method parameters
 126      *
 127      * @return external_function_parameters
 128      * @since Moodle 3.7
 129      */
 130     public static function get_async_backup_links_backup_parameters() {
 131         return new external_function_parameters(
 132                 array(
 133                     'filename' => new external_value(PARAM_FILE, 'Backup filename', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 134                     'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 135                 )
 136          );
 137     }
 138
 139     /**
 140      * Get the data to be used when generating the table row for an asynchronous backup,
 141      * the table row updates via ajax when backup is complete.
 142      *
 143      * @param string $filename The file name of the backup file.
 144      * @param int $contextid The context the backup relates to.
 145      * @since Moodle 3.7
 146      */
 147     public static function get_async_backup_links_backup($filename, $contextid) {
 148         // Release session lock.
 149         \core\session\manager::write_close();
 150
 151         // Parameter validation.
 152         self::validate_parameters(
 153                 self::get_async_backup_links_backup_parameters(),
 154                     array(
 155                         'filename' => $filename,
 156                         'contextid' => $contextid
 157                     )
 158                 );
 159
 160         // Context validation.
 161         list($context, $course, $cm) = get_context_info_array($contextid);
 162         self::validate_context($context);
 163         require_capability('moodle/backup:backupcourse', $context);
 164
 165         if ($cm) {
 166             $filearea = 'activity';
 167         } else {
 168             $filearea = 'course';
 169         }
 170
 171         $results = \async_helper::get_backup_file_info($filename, $filearea, $contextid);
 172
 173         return $results;
 174     }
 175
 176     /**
 177      * Returns description of method result value.
 178      *
 179      * @return external_description
 180      * @since Moodle 3.7
 181      */
 182     public static function get_async_backup_links_backup_returns() {
 183         return new external_single_structure(
 184             array(
 185                'filesize'   => new external_value(PARAM_TEXT, 'Backup file size'),
 186                'fileurl' => new external_value(PARAM_URL, 'Backup file URL'),
 187                'restoreurl' => new external_value(PARAM_URL, 'Backup restore URL'),
 188         ), 'Table row data.');
 189     }
 190     /**
 191      * Returns description of method parameters
 192      *
 193      * @return external_function_parameters
 194      * @since Moodle 3.7
 195      */
 196     public static function get_async_backup_links_restore_parameters() {
 197         return new external_function_parameters(
 198                 array(
 199                     'backupid' => new external_value(PARAM_ALPHANUMEXT, 'Backup id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 200                     'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 201                 )
 202         );
 203     }
 204
 205     /**
 206      * Get the data to be used when generating the table row for an asynchronous restore,
 207      * the table row updates via ajax when restore is complete.
 208      *
 209      * @param string $backupid The id of the backup record.
 210      * @param int $contextid The context the restore relates to.
 211      * @return array $results The array of results.
 212      * @since Moodle 3.7
 213      */
 214     public static function get_async_backup_links_restore($backupid, $contextid) {
 215         // Release session lock.
 216         \core\session\manager::write_close();
 217
 218         // Parameter validation.
 219         self::validate_parameters(
 220                 self::get_async_backup_links_restore_parameters(),
 221                     array(
 222                         'backupid' => $backupid,
 223                         'contextid' => $contextid
 224                     )
 225                 );
 226
 227         // Context validation.
 228         $context = context::instance_by_id($contextid);
 229         self::validate_context($context);
 230         require_capability('moodle/restore:restorecourse', $context);
 231
 232         $results = \async_helper::get_restore_url($backupid);
 233
 234         return $results;
 235     }
 236
 237     /**
 238      * Returns description of method result value.
 239      *
 240      * @return external_description
 241      * @since Moodle 3.7
 242      */
 243     public static function get_async_backup_links_restore_returns() {
 244         return new external_single_structure(
 245                 array(
 246                     'restoreurl' => new external_value(PARAM_URL, 'Restore url'),
 247                 ), 'Table row data.');
 248     }
 249 }