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