MDL-27120 backup: fixed docblock and code cleanup
[moodle.git] / backup / util / ui / backup_ui_stage.class.php
1 <?php
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/>.
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  */
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  */
41 abstract class backup_ui_stage extends base_ui_stage {
43     public function __construct(backup_ui $ui, array $params = null) {
44        parent::__construct($ui, $params);
45     }
46     /**
47      * The backup id from the backup controller
48      * @return string
49      */
50     final public function get_backupid() {
51         return $this->get_uniqueid();
52     }
53 }
55 /**
56  * Class representing the initial stage of a backup.
57  *
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  */
63 class backup_ui_stage_initial extends backup_ui_stage {
65     /**
66      * Initial backup stage constructor
67      * @param backup_ui $ui
68      */
69     public function __construct(backup_ui $ui, array $params=null) {
70         $this->stage = backup_ui::STAGE_INITIAL;
71         parent::__construct($ui, $params);
72     }
74     /**
75      * Processes the initial backup stage
76      * @param backup_moodleform $form
77      * @return int The number of changes
78      */
79     public function process(base_moodleform $m = null) {
81         $form = $this->initialise_stage_form();
83         if ($form->is_cancelled()) {
84             $this->ui->cancel_process();
85         }
87         $data = $form->get_data();
88         if ($data && confirm_sesskey()) {
89             $tasks = $this->ui->get_tasks();
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                         }
105                     }
106                 }
107             }
108             // Return the number of changes the user made
109             return $changes;
110         } else {
111             return false;
112         }
113     }
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;
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
125             $tasks = $this->ui->get_tasks();
126             // Iterate all tasks by reference
127             $add_settings = array();
128             $dependencies = array();
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                         }
139                         $add_settings[] = array($setting, $task);
140                     }
141                     // Then add all dependencies
142                     foreach ($settings as &$setting) {
143                         if ($setting->get_name() == 'filename') {
144                             continue;
145                         }
146                         $dependencies[] = $setting;
147                     }
148                 }
149             }
150             // Add all settings at once.
151             $form->add_settings($add_settings);
152             // Add dependencies.
153             foreach ($dependencies as $depsetting) {
154                 $form->add_dependencies($depsetting);
155             }
156             $this->stageform = $form;
157         }
158         // Return the form
159         return $this->stageform;
160     }
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.
168  *
169  * @copyright 2010 Sam Hemelryk
170  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
171  */
172 class backup_ui_stage_schema extends backup_ui_stage {
173     /**
174      * Schema stage constructor
175      * @param backup_moodleform $ui
176      */
177     public function __construct(backup_ui $ui, array $params=null) {
178         $this->stage = backup_ui::STAGE_SCHEMA;
179         parent::__construct($ui, $params);
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      */
187     public function process(base_moodleform $form = null) {
188         $form = $this->initialise_stage_form();
189         // Check it wasn't cancelled
190         if ($form->is_cancelled()) {
191             $this->ui->cancel_process();
192         }
194         // Check it has been submit
195         $data = $form->get_data();
196         if ($data && confirm_sesskey()) {
197             // Get the tasks into a var so we can iterate by reference
198             $tasks = $this->ui->get_tasks();
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                         }
216                     }
217                 }
218             }
219             // Return the number of changes the user made
220             return $changes;
221         } else {
222             return false;
223         }
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;
232         if ($this->stageform === null) {
233             $form = new backup_schema_form($this, $PAGE->url);
234             $tasks = $this->ui->get_tasks();
235             $content = '';
236             $courseheading = false;
237             $add_settings = array();
238             $dependencies = array();
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
243                         $form->add_heading('coursesettings', get_string('includeactivities', 'backup'));
244                         $courseheading = true;
245                     }
246                     // First add each setting
247                     foreach ($task->get_settings() as $setting) {
248                         $add_settings[] = array($setting, $task);
249                     }
250                     // The add all the dependencies
251                     foreach ($task->get_settings() as $setting) {
252                         $dependencies[] = $setting;
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') {
262                             $form->add_fixed_setting($setting, $task);
263                         }
264                     }
265                 }
266             }
267             $form->add_settings($add_settings);
268             foreach ($dependencies as $depsetting) {
269                 $form->add_dependencies($depsetting);
270             }
271             $this->stageform = $form;
272         }
273         return $this->stageform;
274     }
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  */
286 class backup_ui_stage_confirmation extends backup_ui_stage {
287     /**
288      * Constructs the stage
289      * @param backup_ui $ui
290      */
291     public function __construct($ui, array $params=null) {
292         $this->stage = backup_ui::STAGE_CONFIRMATION;
293         parent::__construct($ui, $params);
294     }
295     /**
296      * Processes the confirmation stage
297      *
298      * @param backup_moodleform $form
299      * @return int The number of changes the user made
300      */
301     public function process(base_moodleform $form = null) {
302         $form = $this->initialise_stage_form();
303         // Check it hasn't been cancelled
304         if ($form->is_cancelled()) {
305             $this->ui->cancel_process();
306         }
308         $data = $form->get_data();
309         if ($data && confirm_sesskey()) {
310             // Collect into a variable so we can iterate by reference
311             $tasks = $this->ui->get_tasks();
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                     }
323                 }
324             }
325             // Return the number of changes the user made
326             return $changes;
327         } else {
328             return false;
329         }
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;
338         if ($this->stageform === null) {
339             // Get the form
340             $form = new backup_confirmation_form($this, $PAGE->url);
341             $content = '';
342             $courseheading = false;
344             foreach ($this->ui->get_tasks() as $task) {
345                 if ($setting = $task->get_setting('filename')) {
346                     $form->add_heading('filenamesetting', get_string('filename', 'backup'));
347                     if ($setting->get_value() == 'backup.mbz') {
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;
357                 }
358             }
360             foreach ($this->ui->get_tasks() as $task) {
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
366                     $form->add_heading('coursesettings', get_string('includeditems', 'backup'));
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') {
373                         $form->add_fixed_setting($setting, $task);
374                     }
375                 }
376             }
377             $this->stageform = $form;
378         }
379         return $this->stageform;
380     }
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  */
401 class backup_ui_stage_final extends backup_ui_stage {
402     /**
403      * Constructs the final stage
404      * @param backup_ui $ui
405      */
406     public function __construct(backup_ui $ui, array $params=null) {
407         $this->stage = backup_ui::STAGE_FINAL;
408         parent::__construct($ui, $params);
409     }
410     /**
411      * Processes the final stage.
412      *
413      * In this case it ALWAYS passes processing to the previous stage (confirmation)
414      */
415     public function process(base_moodleform $form=null) {
416         return true;
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      */
427     public function display(core_backup_renderer $renderer) {
428         throw new backup_ui_exception('backup_ui_must_execute_first');
429     }
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  */
441 class 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
450      * @param array|null $params
451      * @param array $results
452      */
453     public function __construct(backup_ui $ui, array $params=null, array $results=null) {
454         $this->results = $results;
455         parent::__construct($ui, $params);
456         $this->stage = backup_ui::STAGE_COMPLETE;
457     }
458     /**
459      * Displays the completed backup stage.
460      *
461      * Currently this just involves redirecting to the file browser with an
462      * appropriate message.
463      *
464      * @param core_backup_renderer $renderer
465      * @return string HTML code to echo
466      */
467     public function display(core_backup_renderer $renderer) {
469         // Get the resulting stored_file record
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         }
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();
491         return $output;
492     }