MDL-27120 backup: fixed docblock and code cleanup
[moodle.git] / backup / util / ui / backup_ui_stage.class.php
CommitLineData
1904e9b3
SH
1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * Backup user interface stages
20 *
21 * This file contains the classes required to manage the stages that make up the
22 * backup user interface.
23 * These will be primarily operated a {@see backup_ui} instance.
24 *
25 * @package moodlecore
26 * @copyright 2010 Sam Hemelryk
27 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
28 */
29
30/**
31 * Abstract stage class
32 *
33 * This class should be extended by all backup stages (a requirement of many backup ui functions).
34 * Each stage must then define two abstract methods
35 * - process : To process the stage
36 * - initialise_stage_form : To get a backup_moodleform instance for the stage
37 *
38 * @copyright 2010 Sam Hemelryk
39 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40 */
785d6603
SH
41abstract class backup_ui_stage extends base_ui_stage {
42
43 public function __construct(backup_ui $ui, array $params = null) {
44 parent::__construct($ui, $params);
1904e9b3
SH
45 }
46 /**
47 * The backup id from the backup controller
48 * @return string
49 */
50 final public function get_backupid() {
785d6603 51 return $this->get_uniqueid();
1904e9b3 52 }
1904e9b3
SH
53}
54
55/**
56 * Class representing the initial stage of a backup.
64f93798 57 *
1904e9b3
SH
58 * In this stage the user is required to set the root level settings.
59 *
60 * @copyright 2010 Sam Hemelryk
61 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
62 */
63class backup_ui_stage_initial extends backup_ui_stage {
64
65 /**
66 * Initial backup stage constructor
67 * @param backup_ui $ui
68 */
dd6af534 69 public function __construct(backup_ui $ui, array $params=null) {
1904e9b3 70 $this->stage = backup_ui::STAGE_INITIAL;
dd6af534 71 parent::__construct($ui, $params);
1904e9b3 72 }
4886029c 73
1904e9b3
SH
74 /**
75 * Processes the initial backup stage
76 * @param backup_moodleform $form
77 * @return int The number of changes
78 */
785d6603 79 public function process(base_moodleform $m = null) {
1904e9b3 80
4886029c 81 $form = $this->initialise_stage_form();
1904e9b3 82
4886029c 83 if ($form->is_cancelled()) {
ca3617c5 84 $this->ui->cancel_process();
4886029c 85 }
1904e9b3 86
4886029c
SH
87 $data = $form->get_data();
88 if ($data && confirm_sesskey()) {
785d6603 89 $tasks = $this->ui->get_tasks();
4886029c
SH
90 $changes = 0;
91 foreach ($tasks as &$task) {
92 // We are only interesting in the backup root task for this stage
93 if ($task instanceof backup_root_task) {
94 // Get all settings into a var so we can iterate by reference
95 $settings = $task->get_settings();
96 foreach ($settings as &$setting) {
97 $name = $setting->get_ui_name();
98 if (isset($data->$name) && $data->$name != $setting->get_value()) {
99 $setting->set_value($data->$name);
100 $changes++;
101 } else if (!isset($data->$name) && $setting->get_ui_type() == backup_setting::UI_HTML_CHECKBOX && $setting->get_value()) {
102 $setting->set_value(0);
103 $changes++;
104 }
1904e9b3
SH
105 }
106 }
107 }
4886029c
SH
108 // Return the number of changes the user made
109 return $changes;
110 } else {
111 return false;
1904e9b3 112 }
1904e9b3
SH
113 }
114
115 /**
116 * Initialises the backup_moodleform instance for this stage
117 *
118 * @return backup_initial_form
119 */
120 protected function initialise_stage_form() {
121 global $PAGE;
4886029c
SH
122 if ($this->stageform === null) {
123 $form = new backup_initial_form($this, $PAGE->url);
124 // Store as a variable so we can iterate by reference
785d6603 125 $tasks = $this->ui->get_tasks();
4886029c 126 // Iterate all tasks by reference
01ab87fe
AH
127 $add_settings = array();
128 $dependencies = array();
4886029c
SH
129 foreach ($tasks as &$task) {
130 // For the initial stage we are only interested in the root settings
131 if ($task instanceof backup_root_task) {
132 $form->add_heading('rootsettings', get_string('rootsettings', 'backup'));
133 $settings = $task->get_settings();
134 // First add all settings except the filename setting
135 foreach ($settings as &$setting) {
136 if ($setting->get_name() == 'filename') {
137 continue;
138 }
01ab87fe 139 $add_settings[] = array($setting, $task);
1904e9b3 140 }
4886029c
SH
141 // Then add all dependencies
142 foreach ($settings as &$setting) {
143 if ($setting->get_name() == 'filename') {
144 continue;
145 }
01ab87fe 146 $dependencies[] = $setting;
1904e9b3 147 }
1904e9b3
SH
148 }
149 }
f2bfe26a 150 // Add all settings at once.
01ab87fe 151 $form->add_settings($add_settings);
f2bfe26a 152 // Add dependencies.
01ab87fe 153 foreach ($dependencies as $depsetting) {
67bf6941 154 $form->add_dependencies($depsetting);
01ab87fe 155 }
4886029c 156 $this->stageform = $form;
1904e9b3
SH
157 }
158 // Return the form
4886029c 159 return $this->stageform;
1904e9b3
SH
160 }
161}
162
163/**
164 * Schema stage of backup process
165 *
166 * During the schema stage the user is required to set the settings that relate
167 * to the area that they are backing up as well as its children.
64f93798 168 *
1904e9b3
SH
169 * @copyright 2010 Sam Hemelryk
170 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
171 */
172class backup_ui_stage_schema extends backup_ui_stage {
173 /**
174 * Schema stage constructor
175 * @param backup_moodleform $ui
176 */
dd6af534 177 public function __construct(backup_ui $ui, array $params=null) {
1904e9b3 178 $this->stage = backup_ui::STAGE_SCHEMA;
dd6af534 179 parent::__construct($ui, $params);
1904e9b3
SH
180 }
181 /**
182 * Processes the schema stage
183 *
184 * @param backup_moodleform|null $form
185 * @return int The number of changes the user made
186 */
785d6603 187 public function process(base_moodleform $form = null) {
4886029c
SH
188 $form = $this->initialise_stage_form();
189 // Check it wasn't cancelled
190 if ($form->is_cancelled()) {
ca3617c5 191 $this->ui->cancel_process();
1904e9b3
SH
192 }
193
194 // Check it has been submit
195 $data = $form->get_data();
4886029c
SH
196 if ($data && confirm_sesskey()) {
197 // Get the tasks into a var so we can iterate by reference
785d6603 198 $tasks = $this->ui->get_tasks();
4886029c
SH
199 $changes = 0;
200 // Iterate all tasks by reference
201 foreach ($tasks as &$task) {
202 // We are only interested in schema settings
203 if (!($task instanceof backup_root_task)) {
204 // Store as a variable so we can iterate by reference
205 $settings = $task->get_settings();
206 // Iterate by reference
207 foreach ($settings as &$setting) {
208 $name = $setting->get_ui_name();
209 if (isset($data->$name) && $data->$name != $setting->get_value()) {
210 $setting->set_value($data->$name);
211 $changes++;
212 } else if (!isset($data->$name) && $setting->get_ui_type() == backup_setting::UI_HTML_CHECKBOX && $setting->get_value()) {
213 $setting->set_value(0);
214 $changes++;
215 }
1904e9b3
SH
216 }
217 }
218 }
4886029c
SH
219 // Return the number of changes the user made
220 return $changes;
221 } else {
222 return false;
64f93798 223 }
1904e9b3
SH
224 }
225 /**
226 * Creates the backup_schema_form instance for this stage
227 *
228 * @return backup_schema_form
229 */
230 protected function initialise_stage_form() {
231 global $PAGE;
4886029c
SH
232 if ($this->stageform === null) {
233 $form = new backup_schema_form($this, $PAGE->url);
785d6603 234 $tasks = $this->ui->get_tasks();
4886029c
SH
235 $content = '';
236 $courseheading = false;
01ab87fe
AH
237 $add_settings = array();
238 $dependencies = array();
4886029c
SH
239 foreach ($tasks as $task) {
240 if (!($task instanceof backup_root_task)) {
241 if (!$courseheading) {
242 // If we havn't already display a course heading to group nicely
573cdf85 243 $form->add_heading('coursesettings', get_string('includeactivities', 'backup'));
4886029c
SH
244 $courseheading = true;
245 }
246 // First add each setting
247 foreach ($task->get_settings() as $setting) {
01ab87fe 248 $add_settings[] = array($setting, $task);
4886029c
SH
249 }
250 // The add all the dependencies
251 foreach ($task->get_settings() as $setting) {
01ab87fe 252 $dependencies[] = $setting;
4886029c
SH
253 }
254 } else if ($this->ui->enforce_changed_dependencies()) {
255 // Only show these settings if dependencies changed them.
256 // Add a root settings heading to group nicely
257 $form->add_heading('rootsettings', get_string('rootsettings', 'backup'));
258 // Iterate all settings and add them to the form as a fixed
259 // setting. We only want schema settings to be editable
260 foreach ($task->get_settings() as $setting) {
261 if ($setting->get_name() != 'filename') {
83c000d9 262 $form->add_fixed_setting($setting, $task);
4886029c 263 }
1904e9b3 264 }
1904e9b3
SH
265 }
266 }
01ab87fe 267 $form->add_settings($add_settings);
f2bfe26a
RT
268 foreach ($dependencies as $depsetting) {
269 $form->add_dependencies($depsetting);
01ab87fe 270 }
4886029c 271 $this->stageform = $form;
1904e9b3 272 }
4886029c 273 return $this->stageform;
1904e9b3
SH
274 }
275}
276
277/**
278 * Confirmation stage
279 *
280 * On this stage the user reviews the setting for the backup and can change the filename
281 * of the file that will be generated.
282 *
283 * @copyright 2010 Sam Hemelryk
284 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
285 */
286class backup_ui_stage_confirmation extends backup_ui_stage {
287 /**
288 * Constructs the stage
289 * @param backup_ui $ui
290 */
dd6af534 291 public function __construct($ui, array $params=null) {
1904e9b3 292 $this->stage = backup_ui::STAGE_CONFIRMATION;
dd6af534 293 parent::__construct($ui, $params);
1904e9b3
SH
294 }
295 /**
296 * Processes the confirmation stage
297 *
298 * @param backup_moodleform $form
299 * @return int The number of changes the user made
300 */
785d6603 301 public function process(base_moodleform $form = null) {
4886029c
SH
302 $form = $this->initialise_stage_form();
303 // Check it hasn't been cancelled
304 if ($form->is_cancelled()) {
ca3617c5 305 $this->ui->cancel_process();
1904e9b3
SH
306 }
307
1904e9b3 308 $data = $form->get_data();
4886029c
SH
309 if ($data && confirm_sesskey()) {
310 // Collect into a variable so we can iterate by reference
785d6603 311 $tasks = $this->ui->get_tasks();
4886029c
SH
312 $changes = 0;
313 // Iterate each task by reference
314 foreach ($tasks as &$task) {
315 if ($task instanceof backup_root_task) {
316 // At this stage all we are interested in is the filename setting
317 $setting = $task->get_setting('filename');
318 $name = $setting->get_ui_name();
319 if (isset($data->$name) && $data->$name != $setting->get_value()) {
320 $setting->set_value($data->$name);
321 $changes++;
322 }
1904e9b3
SH
323 }
324 }
4886029c
SH
325 // Return the number of changes the user made
326 return $changes;
327 } else {
328 return false;
1904e9b3 329 }
1904e9b3
SH
330 }
331 /**
332 * Creates the backup_confirmation_form instance this stage requires
333 *
334 * @return backup_confirmation_form
335 */
336 protected function initialise_stage_form() {
337 global $PAGE;
4886029c
SH
338 if ($this->stageform === null) {
339 // Get the form
340 $form = new backup_confirmation_form($this, $PAGE->url);
341 $content = '';
342 $courseheading = false;
343
741b96fd
SH
344 foreach ($this->ui->get_tasks() as $task) {
345 if ($setting = $task->get_setting('filename')) {
346 $form->add_heading('filenamesetting', get_string('filename', 'backup'));
12c80f79 347 if ($setting->get_value() == 'backup.mbz') {
741b96fd
SH
348 $format = $this->ui->get_format();
349 $type = $this->ui->get_type();
350 $id = $this->ui->get_controller_id();
351 $users = $this->ui->get_setting_value('users');
352 $anonymised = $this->ui->get_setting_value('anonymize');
353 $setting->set_value(backup_plan_dbops::get_default_backup_filename($format, $type, $id, $users, $anonymised));
354 }
355 $form->add_setting($setting, $task);
356 break;
4886029c 357 }
1904e9b3 358 }
4886029c 359
785d6603 360 foreach ($this->ui->get_tasks() as $task) {
4886029c
SH
361 if ($task instanceof backup_root_task) {
362 // If its a backup root add a root settings heading to group nicely
363 $form->add_heading('rootsettings', get_string('rootsettings', 'backup'));
364 } else if (!$courseheading) {
365 // we havn't already add a course heading
70a10238 366 $form->add_heading('coursesettings', get_string('includeditems', 'backup'));
4886029c
SH
367 $courseheading = true;
368 }
369 // Iterate all settings, doesnt need to happen by reference
370 foreach ($task->get_settings() as $setting) {
371 // For this stage only the filename setting should be editable
372 if ($setting->get_name() != 'filename') {
83c000d9 373 $form->add_fixed_setting($setting, $task);
8f87420a 374 }
1904e9b3
SH
375 }
376 }
4886029c 377 $this->stageform = $form;
1904e9b3 378 }
4886029c 379 return $this->stageform;
1904e9b3
SH
380 }
381}
382
383/**
384 * Final stage of backup
385 *
386 * This stage is special in that it is does not make use of a form. The reason for
387 * this is the order of procession of backup at this stage.
388 * The processesion is:
389 * 1. The final stage will be intialise.
390 * 2. The confirmation stage will be processed.
391 * 3. The backup will be executed
392 * 4. The complete stage will be loaded by execution
393 * 5. The complete stage will be displayed
394 *
395 * This highlights that we neither need a form nor a display method for this stage
396 * we simply need to process.
397 *
398 * @copyright 2010 Sam Hemelryk
399 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
400 */
401class backup_ui_stage_final extends backup_ui_stage {
402 /**
403 * Constructs the final stage
404 * @param backup_ui $ui
405 */
dd6af534 406 public function __construct(backup_ui $ui, array $params=null) {
1904e9b3 407 $this->stage = backup_ui::STAGE_FINAL;
dd6af534 408 parent::__construct($ui, $params);
1904e9b3
SH
409 }
410 /**
411 * Processes the final stage.
412 *
413 * In this case it ALWAYS passes processing to the previous stage (confirmation)
414 */
785d6603 415 public function process(base_moodleform $form=null) {
4886029c 416 return true;
1904e9b3
SH
417 }
418 /**
419 * should NEVER be called... throws an exception
420 */
421 protected function initialise_stage_form() {
422 throw new backup_ui_exception('backup_ui_must_execute_first');
423 }
424 /**
425 * should NEVER be called... throws an exception
426 */
748e9651 427 public function display(core_backup_renderer $renderer) {
1904e9b3
SH
428 throw new backup_ui_exception('backup_ui_must_execute_first');
429 }
430}
431
432/**
433 * The completed backup stage
434 *
435 * At this stage everything is done and the user will be redirected to view the
436 * backup file in the file browser.
437 *
438 * @copyright 2010 Sam Hemelryk
439 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
440 */
441class backup_ui_stage_complete extends backup_ui_stage_final {
442 /**
443 * The results of the backup execution
444 * @var array
445 */
446 protected $results;
447 /**
448 * Constructs the complete backup stage
449 * @param backup_ui $ui
dd6af534 450 * @param array|null $params
1904e9b3
SH
451 * @param array $results
452 */
dd6af534 453 public function __construct(backup_ui $ui, array $params=null, array $results=null) {
1904e9b3 454 $this->results = $results;
dd6af534 455 parent::__construct($ui, $params);
4886029c 456 $this->stage = backup_ui::STAGE_COMPLETE;
1904e9b3
SH
457 }
458 /**
459 * Displays the completed backup stage.
460 *
748e9651 461 * Currently this just involves redirecting to the file browser with an
1904e9b3 462 * appropriate message.
4886029c 463 *
748e9651
PS
464 * @param core_backup_renderer $renderer
465 * @return string HTML code to echo
1904e9b3 466 */
748e9651 467 public function display(core_backup_renderer $renderer) {
64f93798 468
1904e9b3 469 // Get the resulting stored_file record
d0da42d1
DC
470 $type = $this->get_ui()->get_controller()->get_type();
471 $courseid = $this->get_ui()->get_controller()->get_courseid();
472 switch ($type) {
473 case 'activity':
474 $cmid = $this->get_ui()->get_controller()->get_id();
475 $cm = get_coursemodule_from_id(null, $cmid, $courseid);
476 $modcontext = get_context_instance(CONTEXT_MODULE, $cm->id);
477 $restorerul = new moodle_url('/backup/restorefile.php', array('contextid'=>$modcontext->id));
478 break;
479 case 'course':
480 default:
481 $coursecontext = get_context_instance(CONTEXT_COURSE, $courseid);
482 $restorerul = new moodle_url('/backup/restorefile.php', array('contextid'=>$coursecontext->id));
483 }
4886029c 484
748e9651
PS
485 $output = '';
486 $output .= $renderer->box_start();
487 $output .= $renderer->notification(get_string('executionsuccess', 'backup'), 'notifysuccess');
488 $output .= $renderer->continue_button($restorerul);
489 $output .= $renderer->box_end();
490
491 return $output;
1904e9b3 492 }
b46ba22b 493}