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         }
  95
  96         $results = array();
  97         foreach ($backupids as $backupid) {
  98             $results[] = backup_controller_dbops::get_progress($backupid);
  99         }
 100
 101         return $results;
 102     }
 103
 104     /**
 105      * Returns description of method result value
 106      *
 107      * @return external_description
 108      * @since Moodle 3.7
 109      */
 110     public static function get_async_backup_progress_returns() {
 111         return new external_multiple_structure(
 112             new external_single_structure(
 113                 array(
 114                     'status'   => new external_value(PARAM_INT, 'Backup Status'),
 115                     'progress' => new external_value(PARAM_FLOAT, 'Backup progress'),
 116                     'backupid' => new external_value(PARAM_ALPHANUM, 'Backup id'),
 117                     'operation' => new external_value(PARAM_ALPHANUM, 'operation type'),
 118                 ), 'Backup completion status'
 119           ), 'Backup data'
 120         );
 121     }
 122
 123     /**
 124      * Returns description of method parameters
 125      *
 126      * @return external_function_parameters
 127      * @since Moodle 3.7
 128      */
 129     public static function get_async_backup_links_backup_parameters() {
 130         return new external_function_parameters(
 131                 array(
 132                     'filename' => new external_value(PARAM_FILE, 'Backup filename', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 133                     'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 134                 )
 135          );
 136     }
 137
 138     /**
 139      * Get the data to be used when generating the table row for an asynchronous backup,
 140      * the table row updates via ajax when backup is complete.
 141      *
 142      * @param string $filename The file name of the backup file.
 143      * @param int $contextid The context the backup relates to.
 144      * @since Moodle 3.7
 145      */
 146     public static function get_async_backup_links_backup($filename, $contextid) {
 147         // Release session lock.
 148         \core\session\manager::write_close();
 149
 150         // Parameter validation.
 151         self::validate_parameters(
 152                 self::get_async_backup_links_backup_parameters(),
 153                     array(
 154                         'filename' => $filename,
 155                         'contextid' => $contextid
 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         if ($cm) {
 165             $filearea = 'activity';
 166         } else {
 167             $filearea = 'course';
 168         }
 169
 170         $results = \async_helper::get_backup_file_info($filename, $filearea, $contextid);
 171
 172         return $results;
 173     }
 174
 175     /**
 176      * Returns description of method result value.
 177      *
 178      * @return external_description
 179      * @since Moodle 3.7
 180      */
 181     public static function get_async_backup_links_backup_returns() {
 182         return new external_single_structure(
 183             array(
 184                'filesize'   => new external_value(PARAM_TEXT, 'Backup file size'),
 185                'fileurl' => new external_value(PARAM_URL, 'Backup file URL'),
 186                'restoreurl' => new external_value(PARAM_URL, 'Backup restore URL'),
 187         ), 'Table row data.');
 188     }
 189     /**
 190      * Returns description of method parameters
 191      *
 192      * @return external_function_parameters
 193      * @since Moodle 3.7
 194      */
 195     public static function get_async_backup_links_restore_parameters() {
 196         return new external_function_parameters(
 197                 array(
 198                     'backupid' => new external_value(PARAM_ALPHANUMEXT, 'Backup id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 199                     'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
 200                 )
 201         );
 202     }
 203
 204     /**
 205      * Get the data to be used when generating the table row for an asynchronous restore,
 206      * the table row updates via ajax when restore is complete.
 207      *
 208      * @param string $backupid The id of the backup record.
 209      * @param int $contextid The context the restore relates to.
 210      * @return array $results The array of results.
 211      * @since Moodle 3.7
 212      */
 213     public static function get_async_backup_links_restore($backupid, $contextid) {
 214         // Release session lock.
 215         \core\session\manager::write_close();
 216
 217         // Parameter validation.
 218         self::validate_parameters(
 219                 self::get_async_backup_links_restore_parameters(),
 220                     array(
 221                         'backupid' => $backupid,
 222                         'contextid' => $contextid
 223                     )
 224                 );
 225
 226         // Context validation.
 227         $context = context::instance_by_id($contextid);
 228         self::validate_context($context);
 229         require_capability('moodle/restore:restorecourse', $context);
 230
 231         $results = \async_helper::get_restore_url($backupid);
 232
 233         return $results;
 234     }
 235
 236     /**
 237      * Returns description of method result value.
 238      *
 239      * @return external_description
 240      * @since Moodle 3.7
 241      */
 242     public static function get_async_backup_links_restore_returns() {
 243         return new external_single_structure(
 244                 array(
 245                     'restoreurl' => new external_value(PARAM_URL, 'Restore url'),
 246                 ), 'Table row data.');
 247     }
 248 }