2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * External backup API.
20 * @package core_backup
22 * @copyright 2018 Matt Porritt <mattp@catalyst-au.net>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 use core_external\external_api
;
27 use core_external\external_function_parameters
;
28 use core_external\external_multiple_structure
;
29 use core_external\external_single_structure
;
30 use core_external\external_value
;
32 defined('MOODLE_INTERNAL') ||
die;
34 require_once($CFG->dirroot
. '/backup/util/includes/backup_includes.php');
35 require_once($CFG->dirroot
. '/backup/util/includes/restore_includes.php');
38 * Backup external functions.
40 * @package core_backup
42 * @copyright 2018 Matt Porritt <mattp@catalyst-au.net>
43 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
46 class core_backup_external
extends external_api
{
49 * Returns description of method parameters
51 * @return external_function_parameters
54 public static function get_async_backup_progress_parameters() {
55 return new external_function_parameters(
57 'backupids' => new external_multiple_structure(
58 new external_value(PARAM_ALPHANUM
, 'Backup id to get progress for', VALUE_REQUIRED
, null, NULL_ALLOWED
),
59 'Backup id to get progress for', VALUE_REQUIRED
61 'contextid' => new external_value(PARAM_INT
, 'Context id', VALUE_REQUIRED
, null, NULL_NOT_ALLOWED
),
67 * Get asynchronous backup progress.
69 * @param string $backupids The ids of the backup to get progress for.
70 * @param int $contextid The context the backup relates to.
71 * @return array $results The array of results.
74 public static function get_async_backup_progress($backupids, $contextid) {
75 // Release session lock.
76 \core\session\manager
::write_close();
78 // Parameter validation.
79 self
::validate_parameters(
80 self
::get_async_backup_progress_parameters(),
82 'backupids' => $backupids,
83 'contextid' => $contextid
87 // Context validation.
88 list($context, $course, $cm) = get_context_info_array($contextid);
89 self
::validate_context($context);
92 require_capability('moodle/backup:backupactivity', $context);
94 require_capability('moodle/backup:backupcourse', $context);
98 foreach ($backupids as $backupid) {
99 $results[] = backup_controller_dbops
::get_progress($backupid);
106 * Returns description of method result value
108 * @return \core_external\external_description
111 public static function get_async_backup_progress_returns() {
112 return new external_multiple_structure(
113 new external_single_structure(
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'
125 * Returns description of method parameters
127 * @return external_function_parameters
130 public static function get_async_backup_links_backup_parameters() {
131 return new external_function_parameters(
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
),
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.
143 * @param string $filename The file name of the backup file.
144 * @param int $contextid The context the backup relates to.
147 public static function get_async_backup_links_backup($filename, $contextid) {
148 // Release session lock.
149 \core\session\manager
::write_close();
151 // Parameter validation.
152 self
::validate_parameters(
153 self
::get_async_backup_links_backup_parameters(),
155 'filename' => $filename,
156 'contextid' => $contextid
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);
166 $filearea = 'activity';
168 $filearea = 'course';
171 $results = \async_helper
::get_backup_file_info($filename, $filearea, $contextid);
177 * Returns description of method result value.
179 * @return \core_external\external_description
182 public static function get_async_backup_links_backup_returns() {
183 return new external_single_structure(
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.');
191 * Returns description of method parameters
193 * @return external_function_parameters
196 public static function get_async_backup_links_restore_parameters() {
197 return new external_function_parameters(
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
),
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.
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.
214 public static function get_async_backup_links_restore($backupid, $contextid) {
215 // Release session lock.
216 \core\session\manager
::write_close();
218 // Parameter validation.
219 self
::validate_parameters(
220 self
::get_async_backup_links_restore_parameters(),
222 'backupid' => $backupid,
223 'contextid' => $contextid
227 // Context validation.
228 if ($contextid == 0) {
229 $copyrec = \async_helper
::get_backup_record($backupid);
230 $context = context_course
::instance($copyrec->itemid
);
232 $context = context
::instance_by_id($contextid);
234 self
::validate_context($context);
235 require_capability('moodle/restore:restorecourse', $context);
237 $results = \async_helper
::get_restore_url($backupid);
243 * Returns description of method result value.
245 * @return \core_external\external_description
248 public static function get_async_backup_links_restore_returns() {
249 return new external_single_structure(
251 'restoreurl' => new external_value(PARAM_URL
, 'Restore url'),
252 ), 'Table row data.');
256 * Returns description of method parameters
258 * @return external_function_parameters
261 public static function get_copy_progress_parameters() {
262 return new external_function_parameters(
264 'copies' => new external_multiple_structure(
265 new external_single_structure(
267 'backupid' => new external_value(PARAM_ALPHANUM
, 'Backup id'),
268 'restoreid' => new external_value(PARAM_ALPHANUM
, 'Restore id'),
269 'operation' => new external_value(PARAM_ALPHANUM
, 'Operation type'),
278 * Get the data to be used when generating the table row for a course copy,
279 * the table row updates via ajax when copy is complete.
281 * @param array $copies Array of ids.
282 * @return array $results The array of results.
285 public static function get_copy_progress($copies) {
286 // Release session lock.
287 \core\session\manager
::write_close();
289 // Parameter validation.
290 self
::validate_parameters(
291 self
::get_copy_progress_parameters(),
292 array('copies' => $copies)
297 foreach ($copies as $copy) {
299 if ($copy['operation'] == \backup
::OPERATION_BACKUP
) {
300 $copyid = $copy['backupid'];
302 $copyid = $copy['restoreid'];
305 $copyrec = \async_helper
::get_backup_record($copyid);
306 $context = context_course
::instance($copyrec->itemid
);
307 self
::validate_context($context);
309 $copycaps = \core_course\management\helper
::get_course_copy_capabilities();
310 require_all_capabilities($copycaps, $context);
312 if ($copy['operation'] == \backup
::OPERATION_BACKUP
) {
313 $result = \backup_controller_dbops
::get_progress($copyid);
314 if ($result['status'] == \backup
::STATUS_FINISHED_OK
) {
315 $copyid = $copy['restoreid'];
319 $results[] = \backup_controller_dbops
::get_progress($copyid);
326 * Returns description of method result value.
328 * @return \core_external\external_description
331 public static function get_copy_progress_returns() {
332 return new external_multiple_structure(
333 new external_single_structure(
335 'status' => new external_value(PARAM_INT
, 'Copy Status'),
336 'progress' => new external_value(PARAM_FLOAT
, 'Copy progress'),
337 'backupid' => new external_value(PARAM_ALPHANUM
, 'Copy id'),
338 'operation' => new external_value(PARAM_ALPHANUM
, 'Operation type'),
339 ), 'Copy completion status'
345 * Returns description of method parameters
347 * @return external_function_parameters
350 public static function submit_copy_form_parameters() {
351 return new external_function_parameters(
353 'jsonformdata' => new external_value(PARAM_RAW
, 'The data from the create copy form, encoded as a json array')
359 * Submit the course group form.
361 * @param string $jsonformdata The data from the form, encoded as a json array.
362 * @return int new group id.
364 public static function submit_copy_form($jsonformdata) {
366 // Release session lock.
367 \core\session\manager
::write_close();
369 // We always must pass webservice params through validate_parameters.
370 $params = self
::validate_parameters(
371 self
::submit_copy_form_parameters(),
372 array('jsonformdata' => $jsonformdata)
375 $formdata = json_decode($params['jsonformdata']);
378 parse_str($formdata, $data);
380 $context = context_course
::instance($data['courseid']);
381 self
::validate_context($context);
382 $copycaps = \core_course\management\helper
::get_course_copy_capabilities();
383 require_all_capabilities($copycaps, $context);
385 // Submit the form data.
386 $course = get_course($data['courseid']);
387 $mform = new \core_backup\output\
copy_form(
389 array('course' => $course, 'returnto' => '', 'returnurl' => ''),
390 'post', '', ['class' => 'ignoredirty'], true, $data);
391 $mdata = $mform->get_data();
394 // Create the copy task.
395 $copydata = \copy_helper
::process_formdata($mdata);
396 $copyids = \copy_helper
::create_copy($copydata);
398 throw new moodle_exception('copyformfail', 'backup');
401 return json_encode($copyids);
405 * Returns description of method result value.
407 * @return \core_external\external_description
410 public static function submit_copy_form_returns() {
411 return new external_value(PARAM_RAW
, 'JSON response.');