Merge remote-tracking branch 'moodle/master' into MDL-20636_master_new_question_engine
[moodle.git] / backup / moodle2 / backup_stepslib.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  * @package moodlecore
20  * @subpackage backup-moodle2
21  * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 /**
26  * Define all the backup steps that will be used by common tasks in backup
27  */
29 /**
30  * create the temp dir where backup/restore will happen,
31  * delete old directories and create temp ids table
32  */
33 class create_and_clean_temp_stuff extends backup_execution_step {
35     protected function define_execution() {
36         backup_helper::check_and_create_backup_dir($this->get_backupid());// Create backup temp dir
37         backup_helper::clear_backup_dir($this->get_backupid());           // Empty temp dir, just in case
38         backup_helper::delete_old_backup_dirs(time() - (4 * 60 * 60));    // Delete > 4 hours temp dirs
39         backup_controller_dbops::create_backup_ids_temp_table($this->get_backupid()); // Create ids temp table
40     }
41 }
43 /**
44  * delete the temp dir used by backup/restore (conditionally),
45  * delete old directories and drop tem ids table. Note we delete
46  * the directory but not the corresponding log file that will be
47  * there for, at least, 4 hours - only delete_old_backup_dirs()
48  * deletes log files (for easier access to them)
49  */
50 class drop_and_clean_temp_stuff extends backup_execution_step {
52     protected $skipcleaningtempdir = false;
54     protected function define_execution() {
55         global $CFG;
57         backup_controller_dbops::drop_backup_ids_temp_table($this->get_backupid()); // Drop ids temp table
58         backup_helper::delete_old_backup_dirs(time() - (4 * 60 * 60));              // Delete > 4 hours temp dirs
59         // Delete temp dir conditionally:
60         // 1) If $CFG->keeptempdirectoriesonbackup is not enabled
61         // 2) If backup temp dir deletion has been marked to be avoided
62         if (empty($CFG->keeptempdirectoriesonbackup) && !$this->skipcleaningtempdir) {
63             backup_helper::delete_backup_dir($this->get_backupid()); // Empty backup dir
64         }
65     }
67     public function skip_cleaning_temp_dir($skip) {
68         $this->skipcleaningtempdir = $skip;
69     }
70 }
72 /**
73  * Create the directory where all the task (activity/block...) information will be stored
74  */
75 class create_taskbasepath_directory extends backup_execution_step {
77     protected function define_execution() {
78         global $CFG;
79         $basepath = $this->task->get_taskbasepath();
80         if (!check_dir_exists($basepath, true, true)) {
81             throw new backup_step_exception('cannot_create_taskbasepath_directory', $basepath);
82         }
83     }
84 }
86 /**
87  * Abstract structure step, parent of all the activity structure steps. Used to wrap the
88  * activity structure definition within the main <activity ...> tag. Also provides
89  * subplugin support for activities (that must be properly declared)
90  */
91 abstract class backup_activity_structure_step extends backup_structure_step {
93     /**
94      * Add subplugin structure to any element in the activity backup tree
95      *
96      * @param string $subplugintype type of subplugin as defined in activity db/subplugins.php
97      * @param backup_nested_element $element element in the activity backup tree that
98      *                                       we are going to add subplugin information to
99      * @param bool $multiple to define if multiple subplugins can produce information
100      *                       for each instance of $element (true) or no (false)
101      */
102     protected function add_subplugin_structure($subplugintype, $element, $multiple) {
104         global $CFG;
106         // Check the requested subplugintype is a valid one
107         $subpluginsfile = $CFG->dirroot . '/mod/' . $this->task->get_modulename() . '/db/subplugins.php';
108         if (!file_exists($subpluginsfile)) {
109              throw new backup_step_exception('activity_missing_subplugins_php_file', $this->task->get_modulename());
110         }
111         include($subpluginsfile);
112         if (!array_key_exists($subplugintype, $subplugins)) {
113              throw new backup_step_exception('incorrect_subplugin_type', $subplugintype);
114         }
116         // Arrived here, subplugin is correct, let's create the optigroup
117         $optigroupname = $subplugintype . '_' . $element->get_name() . '_subplugin';
118         $optigroup = new backup_optigroup($optigroupname, null, $multiple);
119         $element->add_child($optigroup); // Add optigroup to stay connected since beginning
121         // Get all the optigroup_elements, looking across all the subplugin dirs
122         $subpluginsdirs = get_plugin_list($subplugintype);
123         foreach ($subpluginsdirs as $name => $subpluginsdir) {
124             $classname = 'backup_' . $subplugintype . '_' . $name . '_subplugin';
125             $backupfile = $subpluginsdir . '/backup/moodle2/' . $classname . '.class.php';
126             if (file_exists($backupfile)) {
127                 require_once($backupfile);
128                 $backupsubplugin = new $classname($subplugintype, $name, $optigroup, $this);
129                 // Add subplugin returned structure to optigroup
130                 $backupsubplugin->define_subplugin_structure($element->get_name());
131             }
132         }
133     }
135     /**
136      * As far as activity backup steps are implementing backup_subplugin stuff, they need to
137      * have the parent task available for wrapping purposes (get course/context....)
138      */
139     public function get_task() {
140         return $this->task;
141     }
143     /**
144      * Wraps any activity backup structure within the common 'activity' element
145      * that will include common to all activities information like id, context...
146      */
147     protected function prepare_activity_structure($activitystructure) {
149         // Create the wrap element
150         $activity = new backup_nested_element('activity', array('id', 'moduleid', 'modulename', 'contextid'), null);
152         // Build the tree
153         $activity->add_child($activitystructure);
155         // Set the source
156         $activityarr = array((object)array(
157             'id'         => $this->task->get_activityid(),
158             'moduleid'   => $this->task->get_moduleid(),
159             'modulename' => $this->task->get_modulename(),
160             'contextid'  => $this->task->get_contextid()));
162         $activity->set_source_array($activityarr);
164         // Return the root element (activity)
165         return $activity;
166     }
169 /**
170  * Abstract structure step, to be used by all the activities using core questions stuff
171  * (namely quiz module), supporting question plugins, states and sessions
172  */
173 abstract class backup_questions_activity_structure_step extends backup_activity_structure_step {
175     /**
176      * Attach to $element (usually attempts) the needed backup structures
177      * for question_usages and all the associated data.
178      */
179     protected function add_question_usages($element, $usageidname) {
180         global $CFG;
181         require_once($CFG->dirroot . '/question/engine/lib.php');
183         // Check $element is one nested_backup_element
184         if (! $element instanceof backup_nested_element) {
185             throw new backup_step_exception('question_states_bad_parent_element', $element);
186         }
187         if (! $element->get_final_element($usageidname)) {
188             throw new backup_step_exception('question_states_bad_question_attempt_element', $usageidname);
189         }
191         $quba = new backup_nested_element('question_usage', array('id'),
192                 array('component', 'preferredbehaviour'));
194         $qas = new backup_nested_element('question_attempts');
195         $qa = new backup_nested_element('question_attempt', array('id'), array(
196                 'slot', 'behaviour', 'questionid', 'maxmark', 'minfraction',
197                 'flagged', 'questionsummary', 'rightanswer', 'responsesummary',
198                 'timemodified'));
200         $steps = new backup_nested_element('steps');
201         $step = new backup_nested_element('step', array('id'), array(
202                 'sequencenumber', 'state', 'fraction', 'timecreated', 'userid'));
204         $response = new backup_nested_element('response');
205         $variable = new backup_nested_element('variable', null,  array('name', 'value'));
207         // Build the tree
208         $element->add_child($quba);
209         $quba->add_child($qas);
210         $qas->add_child($qa);
211         $qa->add_child($steps);
212         $steps->add_child($step);
213         $step->add_child($response);
214         $response->add_child($variable);
216         // Set the sources
217         $quba->set_source_table('question_usages',
218                 array('id'                => '../' . $usageidname));
219         $qa->set_source_sql('
220                 SELECT *
221                 FROM {question_attempts}
222                 WHERE questionusageid = :questionusageid
223                 ORDER BY slot',
224                 array('questionusageid'   => backup::VAR_PARENTID));
225         $step->set_source_sql('
226                 SELECT *
227                 FROM {question_attempt_steps}
228                 WHERE questionattemptid = :questionattemptid
229                 ORDER BY sequencenumber',
230                 array('questionattemptid' => backup::VAR_PARENTID));
231         $variable->set_source_table('question_attempt_step_data',
232                 array('attemptstepid'     => backup::VAR_PARENTID));
234         // Annotate ids
235         $qa->annotate_ids('question', 'questionid');
236         $step->annotate_ids('user', 'userid');
238         // Annotate files
239         $fileareas = question_engine::get_all_response_file_areas();
240         foreach ($fileareas as $filearea) {
241             $step->annotate_files('question', $filearea, 'id');
242         }
243     }
247 /**
248  * backup structure step in charge of calculating the categories to be
249  * included in backup, based in the context being backuped (module/course)
250  * and the already annotated questions present in backup_ids_temp
251  */
252 class backup_calculate_question_categories extends backup_execution_step {
254     protected function define_execution() {
255         backup_question_dbops::calculate_question_categories($this->get_backupid(), $this->task->get_contextid());
256     }
259 /**
260  * backup structure step in charge of deleting all the questions annotated
261  * in the backup_ids_temp table
262  */
263 class backup_delete_temp_questions extends backup_execution_step {
265     protected function define_execution() {
266         backup_question_dbops::delete_temp_questions($this->get_backupid());
267     }
270 /**
271  * Abstract structure step, parent of all the block structure steps. Used to wrap the
272  * block structure definition within the main <block ...> tag
273  */
274 abstract class backup_block_structure_step extends backup_structure_step {
276     protected function prepare_block_structure($blockstructure) {
278         // Create the wrap element
279         $block = new backup_nested_element('block', array('id', 'blockname', 'contextid'), null);
281         // Build the tree
282         $block->add_child($blockstructure);
284         // Set the source
285         $blockarr = array((object)array(
286             'id'         => $this->task->get_blockid(),
287             'blockname'  => $this->task->get_blockname(),
288             'contextid'  => $this->task->get_contextid()));
290         $block->set_source_array($blockarr);
292         // Return the root element (block)
293         return $block;
294     }
297 /**
298  * structure step that will generate the module.xml file for the activity,
299  * accumulating various information about the activity, annotating groupings
300  * and completion/avail conf
301  */
302 class backup_module_structure_step extends backup_structure_step {
304     protected function define_structure() {
306         // Define each element separated
308         $module = new backup_nested_element('module', array('id', 'version'), array(
309             'modulename', 'sectionid', 'sectionnumber', 'idnumber',
310             'added', 'score', 'indent', 'visible',
311             'visibleold', 'groupmode', 'groupingid', 'groupmembersonly',
312             'completion', 'completiongradeitemnumber', 'completionview', 'completionexpected',
313             'availablefrom', 'availableuntil', 'showavailability'));
315         $availinfo = new backup_nested_element('availability_info');
316         $availability = new backup_nested_element('availability', array('id'), array(
317             'sourcecmid', 'requiredcompletion', 'gradeitemid', 'grademin', 'grademax'));
319         // attach format plugin structure to $module element, only one allowed
320         $this->add_plugin_structure('format', $module, false);
322         // attach plagiarism plugin structure to $module element, only one allowed
323         $this->add_plugin_structure('plagiarism', $module, false);
325         // Define the tree
326         $module->add_child($availinfo);
327         $availinfo->add_child($availability);
329         // Set the sources
331         $module->set_source_sql('
332             SELECT cm.*, m.version, m.name AS modulename, s.id AS sectionid, s.section AS sectionnumber
333               FROM {course_modules} cm
334               JOIN {modules} m ON m.id = cm.module
335               JOIN {course_sections} s ON s.id = cm.section
336              WHERE cm.id = ?', array(backup::VAR_MODID));
338         $availability->set_source_table('course_modules_availability', array('coursemoduleid' => backup::VAR_MODID));
340         // Define annotations
341         $module->annotate_ids('grouping', 'groupingid');
343         // Return the root element ($module)
344         return $module;
345     }
348 /**
349  * structure step that will generate the section.xml file for the section
350  * annotating files
351  */
352 class backup_section_structure_step extends backup_structure_step {
354     protected function define_structure() {
356         // Define each element separated
358         $section = new backup_nested_element('section', array('id'), array(
359             'number', 'name', 'summary', 'summaryformat', 'sequence', 'visible'));
361         // attach format plugin structure to $section element, only one allowed
362         $this->add_plugin_structure('format', $section, false);
364         // Define sources
366         $section->set_source_table('course_sections', array('id' => backup::VAR_SECTIONID));
368         // Aliases
369         $section->set_source_alias('section', 'number');
371         // Set annotations
372         $section->annotate_files('course', 'section', 'id');
374         return $section;
375     }
378 /**
379  * structure step that will generate the course.xml file for the course, including
380  * course category reference, tags, modules restriction information
381  * and some annotations (files & groupings)
382  */
383 class backup_course_structure_step extends backup_structure_step {
385     protected function define_structure() {
386         global $DB;
388         // Define each element separated
390         $course = new backup_nested_element('course', array('id', 'contextid'), array(
391             'shortname', 'fullname', 'idnumber',
392             'summary', 'summaryformat', 'format', 'showgrades',
393             'newsitems', 'startdate', 'numsections',
394             'marker', 'maxbytes', 'legacyfiles', 'showreports',
395             'visible', 'hiddensections', 'groupmode', 'groupmodeforce',
396             'defaultgroupingid', 'lang', 'theme',
397             'timecreated', 'timemodified',
398             'requested', 'restrictmodules',
399             'enablecompletion', 'completionstartonenrol', 'completionnotify'));
401         $category = new backup_nested_element('category', array('id'), array(
402             'name', 'description'));
404         $tags = new backup_nested_element('tags');
406         $tag = new backup_nested_element('tag', array('id'), array(
407             'name', 'rawname'));
409         $allowedmodules = new backup_nested_element('allowed_modules');
411         $module = new backup_nested_element('module', array(), array('modulename'));
413         // attach format plugin structure to $course element, only one allowed
414         $this->add_plugin_structure('format', $course, false);
416         // attach theme plugin structure to $course element; multiple themes can
417         // save course data (in case of user theme, legacy theme, etc)
418         $this->add_plugin_structure('theme', $course, true);
420         // attach course report plugin structure to $course element; multiple
421         // course reports can save course data if required
422         $this->add_plugin_structure('coursereport', $course, true);
424         // attach plagiarism plugin structure to $course element, only one allowed
425         $this->add_plugin_structure('plagiarism', $course, false);
427         // Build the tree
429         $course->add_child($category);
431         $course->add_child($tags);
432         $tags->add_child($tag);
434         $course->add_child($allowedmodules);
435         $allowedmodules->add_child($module);
437         // Set the sources
439         $courserec = $DB->get_record('course', array('id' => $this->task->get_courseid()));
440         $courserec->contextid = $this->task->get_contextid();
442         $course->set_source_array(array($courserec));
444         $categoryrec = $DB->get_record('course_categories', array('id' => $courserec->category));
446         $category->set_source_array(array($categoryrec));
448         $tag->set_source_sql('SELECT t.id, t.name, t.rawname
449                                 FROM {tag} t
450                                 JOIN {tag_instance} ti ON ti.tagid = t.id
451                                WHERE ti.itemtype = ?
452                                  AND ti.itemid = ?', array(
453                                      backup_helper::is_sqlparam('course'),
454                                      backup::VAR_PARENTID));
456         $module->set_source_sql('SELECT m.name AS modulename
457                                    FROM {modules} m
458                                    JOIN {course_allowed_modules} cam ON m.id = cam.module
459                                   WHERE course = ?', array(backup::VAR_COURSEID));
461         // Some annotations
463         $course->annotate_ids('grouping', 'defaultgroupingid');
465         $course->annotate_files('course', 'summary', null);
466         $course->annotate_files('course', 'legacy', null);
468         // Return root element ($course)
470         return $course;
471     }
474 /**
475  * structure step that will generate the enrolments.xml file for the given course
476  */
477 class backup_enrolments_structure_step extends backup_structure_step {
479     protected function define_structure() {
481         // To know if we are including users
482         $users = $this->get_setting_value('users');
484         // Define each element separated
486         $enrolments = new backup_nested_element('enrolments');
488         $enrols = new backup_nested_element('enrols');
490         $enrol = new backup_nested_element('enrol', array('id'), array(
491             'enrol', 'status', 'sortorder', 'name', 'enrolperiod', 'enrolstartdate',
492             'enrolenddate', 'expirynotify', 'expirytreshold', 'notifyall',
493             'password', 'cost', 'currency', 'roleid', 'customint1', 'customint2', 'customint3',
494             'customint4', 'customchar1', 'customchar2', 'customdec1', 'customdec2',
495             'customtext1', 'customtext2', 'timecreated', 'timemodified'));
497         $userenrolments = new backup_nested_element('user_enrolments');
499         $enrolment = new backup_nested_element('enrolment', array('id'), array(
500             'status', 'userid', 'timestart', 'timeend', 'modifierid',
501             'timemodified'));
503         // Build the tree
504         $enrolments->add_child($enrols);
505         $enrols->add_child($enrol);
506         $enrol->add_child($userenrolments);
507         $userenrolments->add_child($enrolment);
509         // Define sources
511         $enrol->set_source_table('enrol', array('courseid' => backup::VAR_COURSEID));
513         // User enrolments only added only if users included
514         if ($users) {
515             $enrolment->set_source_table('user_enrolments', array('enrolid' => backup::VAR_PARENTID));
516             $enrolment->annotate_ids('user', 'userid');
517         }
519         $enrol->annotate_ids('role', 'roleid');
521         //TODO: let plugins annotate custom fields too and add more children
523         return $enrolments;
524     }
527 /**
528  * structure step that will generate the roles.xml file for the given context, observing
529  * the role_assignments setting to know if that part needs to be included
530  */
531 class backup_roles_structure_step extends backup_structure_step {
533     protected function define_structure() {
535         // To know if we are including role assignments
536         $roleassignments = $this->get_setting_value('role_assignments');
538         // Define each element separated
540         $roles = new backup_nested_element('roles');
542         $overrides = new backup_nested_element('role_overrides');
544         $override = new backup_nested_element('override', array('id'), array(
545             'roleid', 'capability', 'permission', 'timemodified',
546             'modifierid'));
548         $assignments = new backup_nested_element('role_assignments');
550         $assignment = new backup_nested_element('assignment', array('id'), array(
551             'roleid', 'userid', 'timemodified', 'modifierid', 'component', 'itemid',
552             'sortorder'));
554         // Build the tree
555         $roles->add_child($overrides);
556         $roles->add_child($assignments);
558         $overrides->add_child($override);
559         $assignments->add_child($assignment);
561         // Define sources
563         $override->set_source_table('role_capabilities', array('contextid' => backup::VAR_CONTEXTID));
565         // Assignments only added if specified
566         if ($roleassignments) {
567             $assignment->set_source_table('role_assignments', array('contextid' => backup::VAR_CONTEXTID));
568         }
570         // Define id annotations
571         $override->annotate_ids('role', 'roleid');
573         $assignment->annotate_ids('role', 'roleid');
575         $assignment->annotate_ids('user', 'userid');
577         //TODO: how do we annotate the itemid? the meaning depends on the content of component table (skodak)
579         return $roles;
580     }
583 /**
584  * structure step that will generate the roles.xml containing the
585  * list of roles used along the whole backup process. Just raw
586  * list of used roles from role table
587  */
588 class backup_final_roles_structure_step extends backup_structure_step {
590     protected function define_structure() {
592         // Define elements
594         $rolesdef = new backup_nested_element('roles_definition');
596         $role = new backup_nested_element('role', array('id'), array(
597             'name', 'shortname', 'nameincourse', 'description',
598             'sortorder', 'archetype'));
600         // Build the tree
602         $rolesdef->add_child($role);
604         // Define sources
606         $role->set_source_sql("SELECT r.*, rn.name AS nameincourse
607                                  FROM {role} r
608                                  JOIN {backup_ids_temp} bi ON r.id = bi.itemid
609                             LEFT JOIN {role_names} rn ON r.id = rn.roleid AND rn.contextid = ?
610                                 WHERE bi.backupid = ?
611                                   AND bi.itemname = 'rolefinal'", array(backup::VAR_CONTEXTID, backup::VAR_BACKUPID));
613         // Return main element (rolesdef)
614         return $rolesdef;
615     }
618 /**
619  * structure step that will generate the scales.xml containing the
620  * list of scales used along the whole backup process.
621  */
622 class backup_final_scales_structure_step extends backup_structure_step {
624     protected function define_structure() {
626         // Define elements
628         $scalesdef = new backup_nested_element('scales_definition');
630         $scale = new backup_nested_element('scale', array('id'), array(
631             'courseid', 'userid', 'name', 'scale',
632             'description', 'descriptionformat', 'timemodified'));
634         // Build the tree
636         $scalesdef->add_child($scale);
638         // Define sources
640         $scale->set_source_sql("SELECT s.*
641                                   FROM {scale} s
642                                   JOIN {backup_ids_temp} bi ON s.id = bi.itemid
643                                  WHERE bi.backupid = ?
644                                    AND bi.itemname = 'scalefinal'", array(backup::VAR_BACKUPID));
646         // Annotate scale files (they store files in system context, so pass it instead of default one)
647         $scale->annotate_files('grade', 'scale', 'id', get_context_instance(CONTEXT_SYSTEM)->id);
649         // Return main element (scalesdef)
650         return $scalesdef;
651     }
654 /**
655  * structure step that will generate the outcomes.xml containing the
656  * list of outcomes used along the whole backup process.
657  */
658 class backup_final_outcomes_structure_step extends backup_structure_step {
660     protected function define_structure() {
662         // Define elements
664         $outcomesdef = new backup_nested_element('outcomes_definition');
666         $outcome = new backup_nested_element('outcome', array('id'), array(
667             'courseid', 'userid', 'shortname', 'fullname',
668             'scaleid', 'description', 'descriptionformat', 'timecreated',
669             'timemodified','usermodified'));
671         // Build the tree
673         $outcomesdef->add_child($outcome);
675         // Define sources
677         $outcome->set_source_sql("SELECT o.*
678                                     FROM {grade_outcomes} o
679                                     JOIN {backup_ids_temp} bi ON o.id = bi.itemid
680                                    WHERE bi.backupid = ?
681                                      AND bi.itemname = 'outcomefinal'", array(backup::VAR_BACKUPID));
683         // Annotate outcome files (they store files in system context, so pass it instead of default one)
684         $outcome->annotate_files('grade', 'outcome', 'id', get_context_instance(CONTEXT_SYSTEM)->id);
686         // Return main element (outcomesdef)
687         return $outcomesdef;
688     }
691 /**
692  * structure step in charge of constructing the filters.xml file for all the filters found
693  * in activity
694  */
695 class backup_filters_structure_step extends backup_structure_step {
697     protected function define_structure() {
699         // Define each element separated
701         $filters = new backup_nested_element('filters');
703         $actives = new backup_nested_element('filter_actives');
705         $active = new backup_nested_element('filter_active', null, array('filter', 'active'));
707         $configs = new backup_nested_element('filter_configs');
709         $config = new backup_nested_element('filter_config', null, array('filter', 'name', 'value'));
711         // Build the tree
713         $filters->add_child($actives);
714         $filters->add_child($configs);
716         $actives->add_child($active);
717         $configs->add_child($config);
719         // Define sources
721         list($activearr, $configarr) = filter_get_all_local_settings($this->task->get_contextid());
723         $active->set_source_array($activearr);
724         $config->set_source_array($configarr);
726         // Return the root element (filters)
727         return $filters;
728     }
731 /**
732  * structure step in charge of constructing the comments.xml file for all the comments found
733  * in a given context
734  */
735 class backup_comments_structure_step extends backup_structure_step {
737     protected function define_structure() {
739         // Define each element separated
741         $comments = new backup_nested_element('comments');
743         $comment = new backup_nested_element('comment', array('id'), array(
744             'commentarea', 'itemid', 'content', 'format',
745             'userid', 'timecreated'));
747         // Build the tree
749         $comments->add_child($comment);
751         // Define sources
753         $comment->set_source_table('comments', array('contextid' => backup::VAR_CONTEXTID));
755         // Define id annotations
757         $comment->annotate_ids('user', 'userid');
759         // Return the root element (comments)
760         return $comments;
761     }
764 /**
765  * structure step in charge of constructing the gradebook.xml file for all the gradebook config in the course
766  * NOTE: the backup of the grade items themselves is handled by backup_activity_grades_structure_step
767  */
768 class backup_gradebook_structure_step extends backup_structure_step {
770     /**
771      * We need to decide conditionally, based on dynamic information
772      * about the execution of this step. Only will be executed if all
773      * the module gradeitems have been already included in backup
774      */
775     protected function execute_condition() {
776         return backup_plan_dbops::require_gradebook_backup($this->get_courseid(), $this->get_backupid());
777     }
779     protected function define_structure() {
781         // are we including user info?
782         $userinfo = $this->get_setting_value('users');
784         $gradebook = new backup_nested_element('gradebook');
786         //grade_letters are done in backup_activity_grades_structure_step()
788         //calculated grade items
789         $grade_items = new backup_nested_element('grade_items');
790         $grade_item = new backup_nested_element('grade_item', array('id'), array(
791             'categoryid', 'itemname', 'itemtype', 'itemmodule',
792             'iteminstance', 'itemnumber', 'iteminfo', 'idnumber',
793             'calculation', 'gradetype', 'grademax', 'grademin',
794             'scaleid', 'outcomeid', 'gradepass', 'multfactor',
795             'plusfactor', 'aggregationcoef', 'sortorder', 'display',
796             'decimals', 'hidden', 'locked', 'locktime',
797             'needsupdate', 'timecreated', 'timemodified'));
799         $grade_grades = new backup_nested_element('grade_grades');
800         $grade_grade = new backup_nested_element('grade_grade', array('id'), array(
801             'userid', 'rawgrade', 'rawgrademax', 'rawgrademin',
802             'rawscaleid', 'usermodified', 'finalgrade', 'hidden',
803             'locked', 'locktime', 'exported', 'overridden',
804             'excluded', 'feedback', 'feedbackformat', 'information',
805             'informationformat', 'timecreated', 'timemodified'));
807         //grade_categories
808         $grade_categories = new backup_nested_element('grade_categories');
809         $grade_category   = new backup_nested_element('grade_category', array('id'), array(
810                 //'courseid', 
811                 'parent', 'depth', 'path', 'fullname', 'aggregation', 'keephigh',
812                 'dropload', 'aggregateonlygraded', 'aggregateoutcomes', 'aggregatesubcats',
813                 'timecreated', 'timemodified', 'hidden'));
815         $letters = new backup_nested_element('grade_letters');
816         $letter = new backup_nested_element('grade_letter', 'id', array(
817             'lowerboundary', 'letter'));
819         $grade_settings = new backup_nested_element('grade_settings');
820         $grade_setting = new backup_nested_element('grade_setting', 'id', array(
821             'name', 'value'));
824         // Build the tree
825         $gradebook->add_child($grade_categories);
826         $grade_categories->add_child($grade_category);
828         $gradebook->add_child($grade_items);
829         $grade_items->add_child($grade_item);
830         $grade_item->add_child($grade_grades);
831         $grade_grades->add_child($grade_grade);
833         $gradebook->add_child($letters);
834         $letters->add_child($letter);
836         $gradebook->add_child($grade_settings);
837         $grade_settings->add_child($grade_setting);
839         // Define sources
841         //Include manual, category and the course grade item
842         $grade_items_sql ="SELECT * FROM {grade_items}
843                            WHERE courseid = :courseid
844                            AND (itemtype='manual' OR itemtype='course' OR itemtype='category')";
845         $grade_items_params = array('courseid'=>backup::VAR_COURSEID);
846         $grade_item->set_source_sql($grade_items_sql, $grade_items_params);
848         if ($userinfo) {
849             $grade_grade->set_source_table('grade_grades', array('itemid' => backup::VAR_PARENTID));
850         }
852         $grade_category_sql = "SELECT gc.*, gi.sortorder
853                                FROM {grade_categories} gc
854                                JOIN {grade_items} gi ON (gi.iteminstance = gc.id)
855                                WHERE gc.courseid = :courseid
856                                AND (gi.itemtype='course' OR gi.itemtype='category')
857                                ORDER BY gc.parent ASC";//need parent categories before their children
858         $grade_category_params = array('courseid'=>backup::VAR_COURSEID);
859         $grade_category->set_source_sql($grade_category_sql, $grade_category_params);
861         $letter->set_source_table('grade_letters', array('contextid' => backup::VAR_CONTEXTID));
863         $grade_setting->set_source_table('grade_settings', array('courseid' => backup::VAR_COURSEID));
865         // Annotations (both as final as far as they are going to be exported in next steps)
866         $grade_item->annotate_ids('scalefinal', 'scaleid'); // Straight as scalefinal because it's > 0
867         $grade_item->annotate_ids('outcomefinal', 'outcomeid');
869         //just in case there are any users not already annotated by the activities
870         $grade_grade->annotate_ids('userfinal', 'userid');
872         // Return the root element
873         return $gradebook;
874     }
877 /**
878  * structure step in charge if constructing the completion.xml file for all the users completion
879  * information in a given activity
880  */
881 class backup_userscompletion_structure_step extends backup_structure_step {
883     protected function define_structure() {
885         // Define each element separated
887         $completions = new backup_nested_element('completions');
889         $completion = new backup_nested_element('completion', array('id'), array(
890             'userid', 'completionstate', 'viewed', 'timemodified'));
892         // Build the tree
894         $completions->add_child($completion);
896         // Define sources
898         $completion->set_source_table('course_modules_completion', array('coursemoduleid' => backup::VAR_MODID));
900         // Define id annotations
902         $completion->annotate_ids('user', 'userid');
904         // Return the root element (completions)
905         return $completions;
906     }
909 /**
910  * structure step in charge of constructing the main groups.xml file for all the groups and
911  * groupings information already annotated
912  */
913 class backup_groups_structure_step extends backup_structure_step {
915     protected function define_structure() {
917         // To know if we are including users
918         $users = $this->get_setting_value('users');
920         // Define each element separated
922         $groups = new backup_nested_element('groups');
924         $group = new backup_nested_element('group', array('id'), array(
925             'name', 'description', 'descriptionformat', 'enrolmentkey',
926             'picture', 'hidepicture', 'timecreated', 'timemodified'));
928         $members = new backup_nested_element('group_members');
930         $member = new backup_nested_element('group_member', array('id'), array(
931             'userid', 'timeadded'));
933         $groupings = new backup_nested_element('groupings');
935         $grouping = new backup_nested_element('grouping', 'id', array(
936             'name', 'description', 'descriptionformat', 'configdata',
937             'timecreated', 'timemodified'));
939         $groupinggroups = new backup_nested_element('grouping_groups');
941         $groupinggroup = new backup_nested_element('grouping_group', array('id'), array(
942             'groupid', 'timeadded'));
944         // Build the tree
946         $groups->add_child($group);
947         $groups->add_child($groupings);
949         $group->add_child($members);
950         $members->add_child($member);
952         $groupings->add_child($grouping);
953         $grouping->add_child($groupinggroups);
954         $groupinggroups->add_child($groupinggroup);
956         // Define sources
958         $group->set_source_sql("
959             SELECT g.*
960               FROM {groups} g
961               JOIN {backup_ids_temp} bi ON g.id = bi.itemid
962              WHERE bi.backupid = ?
963                AND bi.itemname = 'groupfinal'", array(backup::VAR_BACKUPID));
965         // This only happens if we are including users
966         if ($users) {
967             $member->set_source_table('groups_members', array('groupid' => backup::VAR_PARENTID));
968         }
970         $grouping->set_source_sql("
971             SELECT g.*
972               FROM {groupings} g
973               JOIN {backup_ids_temp} bi ON g.id = bi.itemid
974              WHERE bi.backupid = ?
975                AND bi.itemname = 'groupingfinal'", array(backup::VAR_BACKUPID));
977         $groupinggroup->set_source_table('groupings_groups', array('groupingid' => backup::VAR_PARENTID));
979         // Define id annotations (as final)
981         $member->annotate_ids('userfinal', 'userid');
983         // Define file annotations
985         $group->annotate_files('group', 'description', 'id');
986         $group->annotate_files('group', 'icon', 'id');
987         $grouping->annotate_files('grouping', 'description', 'id');
989         // Return the root element (groups)
990         return $groups;
991     }
994 /**
995  * structure step in charge of constructing the main users.xml file for all the users already
996  * annotated (final). Includes custom profile fields, preferences, tags, role assignments and
997  * overrides.
998  */
999 class backup_users_structure_step extends backup_structure_step {
1001     protected function define_structure() {
1002         global $CFG;
1004         // To know if we are anonymizing users
1005         $anonymize = $this->get_setting_value('anonymize');
1006         // To know if we are including role assignments
1007         $roleassignments = $this->get_setting_value('role_assignments');
1009         // Define each element separated
1011         $users = new backup_nested_element('users');
1013         // Create the array of user fields by hand, as far as we have various bits to control
1014         // anonymize option, password backup, mnethostid...
1016         // First, the fields not needing anonymization nor special handling
1017         $normalfields = array(
1018             'confirmed', 'policyagreed', 'deleted',
1019             'lang', 'theme', 'timezone', 'firstaccess',
1020             'lastaccess', 'lastlogin', 'currentlogin',
1021             'mailformat', 'maildigest', 'maildisplay', 'htmleditor',
1022             'ajax', 'autosubscribe', 'trackforums', 'timecreated',
1023             'timemodified', 'trustbitmask', 'screenreader');
1025         // Then, the fields potentially needing anonymization
1026         $anonfields = array(
1027             'username', 'idnumber', 'firstname', 'lastname',
1028             'email', 'icq', 'skype',
1029             'yahoo', 'aim', 'msn', 'phone1',
1030             'phone2', 'institution', 'department', 'address',
1031             'city', 'country', 'lastip', 'picture',
1032             'url', 'description', 'descriptionformat', 'imagealt', 'auth');
1034         // Add anonymized fields to $userfields with custom final element
1035         foreach ($anonfields as $field) {
1036             if ($anonymize) {
1037                 $userfields[] = new anonymizer_final_element($field);
1038             } else {
1039                 $userfields[] = $field; // No anonymization, normally added
1040             }
1041         }
1043         // mnethosturl requires special handling (custom final element)
1044         $userfields[] = new mnethosturl_final_element('mnethosturl');
1046         // password added conditionally
1047         if (!empty($CFG->includeuserpasswordsinbackup)) {
1048             $userfields[] = 'password';
1049         }
1051         // Merge all the fields
1052         $userfields = array_merge($userfields, $normalfields);
1054         $user = new backup_nested_element('user', array('id', 'contextid'), $userfields);
1056         $customfields = new backup_nested_element('custom_fields');
1058         $customfield = new backup_nested_element('custom_field', array('id'), array(
1059             'field_name', 'field_type', 'field_data'));
1061         $tags = new backup_nested_element('tags');
1063         $tag = new backup_nested_element('tag', array('id'), array(
1064             'name', 'rawname'));
1066         $preferences = new backup_nested_element('preferences');
1068         $preference = new backup_nested_element('preference', array('id'), array(
1069             'name', 'value'));
1071         $roles = new backup_nested_element('roles');
1073         $overrides = new backup_nested_element('role_overrides');
1075         $override = new backup_nested_element('override', array('id'), array(
1076             'roleid', 'capability', 'permission', 'timemodified',
1077             'modifierid'));
1079         $assignments = new backup_nested_element('role_assignments');
1081         $assignment = new backup_nested_element('assignment', array('id'), array(
1082             'roleid', 'userid', 'timemodified', 'modifierid', 'component', //TODO: MDL-22793 add itemid here
1083             'sortorder'));
1085         // Build the tree
1087         $users->add_child($user);
1089         $user->add_child($customfields);
1090         $customfields->add_child($customfield);
1092         $user->add_child($tags);
1093         $tags->add_child($tag);
1095         $user->add_child($preferences);
1096         $preferences->add_child($preference);
1098         $user->add_child($roles);
1100         $roles->add_child($overrides);
1101         $roles->add_child($assignments);
1103         $overrides->add_child($override);
1104         $assignments->add_child($assignment);
1106         // Define sources
1108         $user->set_source_sql('SELECT u.*, c.id AS contextid, m.wwwroot AS mnethosturl
1109                                  FROM {user} u
1110                                  JOIN {backup_ids_temp} bi ON bi.itemid = u.id
1111                                  JOIN {context} c ON c.instanceid = u.id
1112                             LEFT JOIN {mnet_host} m ON m.id = u.mnethostid
1113                                 WHERE bi.backupid = ?
1114                                   AND bi.itemname = ?
1115                                   AND c.contextlevel = ?', array(
1116                                       backup_helper::is_sqlparam($this->get_backupid()),
1117                                       backup_helper::is_sqlparam('userfinal'),
1118                                       backup_helper::is_sqlparam(CONTEXT_USER)));
1120         // All the rest on information is only added if we arent
1121         // in an anonymized backup
1122         if (!$anonymize) {
1123             $customfield->set_source_sql('SELECT f.id, f.shortname, f.datatype, d.data
1124                                             FROM {user_info_field} f
1125                                             JOIN {user_info_data} d ON d.fieldid = f.id
1126                                            WHERE d.userid = ?', array(backup::VAR_PARENTID));
1128             $customfield->set_source_alias('shortname', 'field_name');
1129             $customfield->set_source_alias('datatype',  'field_type');
1130             $customfield->set_source_alias('data',      'field_data');
1132             $tag->set_source_sql('SELECT t.id, t.name, t.rawname
1133                                     FROM {tag} t
1134                                     JOIN {tag_instance} ti ON ti.tagid = t.id
1135                                    WHERE ti.itemtype = ?
1136                                      AND ti.itemid = ?', array(
1137                                          backup_helper::is_sqlparam('user'),
1138                                          backup::VAR_PARENTID));
1140             $preference->set_source_table('user_preferences', array('userid' => backup::VAR_PARENTID));
1142             $override->set_source_table('role_capabilities', array('contextid' => '/users/user/contextid'));
1144             // Assignments only added if specified
1145             if ($roleassignments) {
1146                 $assignment->set_source_table('role_assignments', array('contextid' => '/users/user/contextid'));
1147             }
1149             // Define id annotations (as final)
1150             $override->annotate_ids('rolefinal', 'roleid');
1151         }
1153         // Return root element (users)
1154         return $users;
1155     }
1158 /**
1159  * structure step in charge of constructing the block.xml file for one
1160  * given block (instance and positions). If the block has custom DB structure
1161  * that will go to a separate file (different step defined in block class)
1162  */
1163 class backup_block_instance_structure_step extends backup_structure_step {
1165     protected function define_structure() {
1166         global $DB;
1168         // Define each element separated
1170         $block = new backup_nested_element('block', array('id', 'contextid', 'version'), array(
1171             'blockname', 'parentcontextid', 'showinsubcontexts', 'pagetypepattern',
1172             'subpagepattern', 'defaultregion', 'defaultweight', 'configdata'));
1174         $positions = new backup_nested_element('block_positions');
1176         $position = new backup_nested_element('block_position', array('id'), array(
1177             'contextid', 'pagetype', 'subpage', 'visible',
1178             'region', 'weight'));
1180         // Build the tree
1182         $block->add_child($positions);
1183         $positions->add_child($position);
1185         // Transform configdata information if needed (process links and friends)
1186         $blockrec = $DB->get_record('block_instances', array('id' => $this->task->get_blockid()));
1187         if ($attrstotransform = $this->task->get_configdata_encoded_attributes()) {
1188             $configdata = (array)unserialize(base64_decode($blockrec->configdata));
1189             foreach ($configdata as $attribute => $value) {
1190                 if (in_array($attribute, $attrstotransform)) {
1191                     $configdata[$attribute] = $this->contenttransformer->process($value);
1192                 }
1193             }
1194             $blockrec->configdata = base64_encode(serialize((object)$configdata));
1195         }
1196         $blockrec->contextid = $this->task->get_contextid();
1197         // Get the version of the block
1198         $blockrec->version = $DB->get_field('block', 'version', array('name' => $this->task->get_blockname()));
1200         // Define sources
1202         $block->set_source_array(array($blockrec));
1204         $position->set_source_table('block_positions', array('blockinstanceid' => backup::VAR_PARENTID));
1206         // File anotations (for fileareas specified on each block)
1207         foreach ($this->task->get_fileareas() as $filearea) {
1208             $block->annotate_files('block_' . $this->task->get_blockname(), $filearea, null);
1209         }
1211         // Return the root element (block)
1212         return $block;
1213     }
1216 /**
1217  * structure step in charge of constructing the logs.xml file for all the log records found
1218  * in course. Note that we are sending to backup ALL the log records having cmid = 0. That
1219  * includes some records that won't be restoreable (like 'upload', 'calendar'...) but we do
1220  * that just in case they become restored some day in the future
1221  */
1222 class backup_course_logs_structure_step extends backup_structure_step {
1224     protected function define_structure() {
1226         // Define each element separated
1228         $logs = new backup_nested_element('logs');
1230         $log = new backup_nested_element('log', array('id'), array(
1231             'time', 'userid', 'ip', 'module',
1232             'action', 'url', 'info'));
1234         // Build the tree
1236         $logs->add_child($log);
1238         // Define sources (all the records belonging to the course, having cmid = 0)
1240         $log->set_source_table('log', array('course' => backup::VAR_COURSEID, 'cmid' => backup_helper::is_sqlparam(0)));
1242         // Annotations
1243         // NOTE: We don't annotate users from logs as far as they MUST be
1244         //       always annotated by the course (enrol, ras... whatever)
1246         // Return the root element (logs)
1248         return $logs;
1249     }
1252 /**
1253  * structure step in charge of constructing the logs.xml file for all the log records found
1254  * in activity
1255  */
1256 class backup_activity_logs_structure_step extends backup_structure_step {
1258     protected function define_structure() {
1260         // Define each element separated
1262         $logs = new backup_nested_element('logs');
1264         $log = new backup_nested_element('log', array('id'), array(
1265             'time', 'userid', 'ip', 'module',
1266             'action', 'url', 'info'));
1268         // Build the tree
1270         $logs->add_child($log);
1272         // Define sources
1274         $log->set_source_table('log', array('cmid' => backup::VAR_MODID));
1276         // Annotations
1277         // NOTE: We don't annotate users from logs as far as they MUST be
1278         //       always annotated by the activity (true participants).
1280         // Return the root element (logs)
1282         return $logs;
1283     }
1286 /**
1287  * structure in charge of constructing the inforef.xml file for all the items we want
1288  * to have referenced there (users, roles, files...)
1289  */
1290 class backup_inforef_structure_step extends backup_structure_step {
1292     protected function define_structure() {
1294         // Items we want to include in the inforef file.
1295         $items = backup_helper::get_inforef_itemnames();
1297         // Build the tree
1299         $inforef = new backup_nested_element('inforef');
1301         // For each item, conditionally, if there are already records, build element
1302         foreach ($items as $itemname) {
1303             if (backup_structure_dbops::annotations_exist($this->get_backupid(), $itemname)) {
1304                 $elementroot = new backup_nested_element($itemname . 'ref');
1305                 $element = new backup_nested_element($itemname, array(), array('id'));
1306                 $inforef->add_child($elementroot);
1307                 $elementroot->add_child($element);
1308                 $element->set_source_sql("
1309                     SELECT itemid AS id
1310                      FROM {backup_ids_temp}
1311                     WHERE backupid = ?
1312                       AND itemname = ?",
1313                    array(backup::VAR_BACKUPID, backup_helper::is_sqlparam($itemname)));
1314             }
1315         }
1317         // We don't annotate anything there, but rely in the next step
1318         // (move_inforef_annotations_to_final) that will change all the
1319         // already saved 'inforref' entries to their 'final' annotations.
1320         return $inforef;
1321     }
1324 /**
1325  * This step will get all the annotations already processed to inforef.xml file and
1326  * transform them into 'final' annotations.
1327  */
1328 class move_inforef_annotations_to_final extends backup_execution_step {
1330     protected function define_execution() {
1332         // Items we want to include in the inforef file
1333         $items = backup_helper::get_inforef_itemnames();
1334         foreach ($items as $itemname) {
1335             // Delegate to dbops
1336             backup_structure_dbops::move_annotations_to_final($this->get_backupid(), $itemname);
1337         }
1338     }
1341 /**
1342  * structure in charge of constructing the files.xml file with all the
1343  * annotated (final) files along the process. At, the same time, and
1344  * using one specialised nested_element, will copy them form moodle storage
1345  * to backup storage
1346  */
1347 class backup_final_files_structure_step extends backup_structure_step {
1349     protected function define_structure() {
1351         // Define elements
1353         $files = new backup_nested_element('files');
1355         $file = new file_nested_element('file', array('id'), array(
1356             'contenthash', 'contextid', 'component', 'filearea', 'itemid',
1357             'filepath', 'filename', 'userid', 'filesize',
1358             'mimetype', 'status', 'timecreated', 'timemodified',
1359             'source', 'author', 'license', 'sortorder'));
1361         // Build the tree
1363         $files->add_child($file);
1365         // Define sources
1367         $file->set_source_sql("SELECT f.*
1368                                  FROM {files} f
1369                                  JOIN {backup_ids_temp} bi ON f.id = bi.itemid
1370                                 WHERE bi.backupid = ?
1371                                   AND bi.itemname = 'filefinal'", array(backup::VAR_BACKUPID));
1373         return $files;
1374     }
1377 /**
1378  * Structure step in charge of creating the main moodle_backup.xml file
1379  * where all the information related to the backup, settings, license and
1380  * other information needed on restore is added*/
1381 class backup_main_structure_step extends backup_structure_step {
1383     protected function define_structure() {
1385         global $CFG;
1387         $info = array();
1389         $info['name'] = $this->get_setting_value('filename');
1390         $info['moodle_version'] = $CFG->version;
1391         $info['moodle_release'] = $CFG->release;
1392         $info['backup_version'] = $CFG->backup_version;
1393         $info['backup_release'] = $CFG->backup_release;
1394         $info['backup_date']    = time();
1395         $info['backup_uniqueid']= $this->get_backupid();
1396         $info['mnet_remoteusers']=backup_controller_dbops::backup_includes_mnet_remote_users($this->get_backupid());
1397         $info['original_wwwroot']=$CFG->wwwroot;
1398         $info['original_site_identifier_hash'] = md5(get_site_identifier());
1399         $info['original_course_id'] = $this->get_courseid();
1400         $originalcourseinfo = backup_controller_dbops::backup_get_original_course_info($this->get_courseid());
1401         $info['original_course_fullname']  = $originalcourseinfo->fullname;
1402         $info['original_course_shortname'] = $originalcourseinfo->shortname;
1403         $info['original_course_startdate'] = $originalcourseinfo->startdate;
1404         $info['original_course_contextid'] = get_context_instance(CONTEXT_COURSE, $this->get_courseid())->id;
1405         $info['original_system_contextid'] = get_context_instance(CONTEXT_SYSTEM)->id;
1407         // Get more information from controller
1408         list($dinfo, $cinfo, $sinfo) = backup_controller_dbops::get_moodle_backup_information($this->get_backupid());
1410         // Define elements
1412         $moodle_backup = new backup_nested_element('moodle_backup');
1414         $information = new backup_nested_element('information', null, array(
1415             'name', 'moodle_version', 'moodle_release', 'backup_version',
1416             'backup_release', 'backup_date', 'mnet_remoteusers', 'original_wwwroot',
1417             'original_site_identifier_hash', 'original_course_id',
1418             'original_course_fullname', 'original_course_shortname', 'original_course_startdate',
1419             'original_course_contextid', 'original_system_contextid'));
1421         $details = new backup_nested_element('details');
1423         $detail = new backup_nested_element('detail', array('backup_id'), array(
1424             'type', 'format', 'interactive', 'mode',
1425             'execution', 'executiontime'));
1427         $contents = new backup_nested_element('contents');
1429         $activities = new backup_nested_element('activities');
1431         $activity = new backup_nested_element('activity', null, array(
1432             'moduleid', 'sectionid', 'modulename', 'title',
1433             'directory'));
1435         $sections = new backup_nested_element('sections');
1437         $section = new backup_nested_element('section', null, array(
1438             'sectionid', 'title', 'directory'));
1440         $course = new backup_nested_element('course', null, array(
1441             'courseid', 'title', 'directory'));
1443         $settings = new backup_nested_element('settings');
1445         $setting = new backup_nested_element('setting', null, array(
1446             'level', 'section', 'activity', 'name', 'value'));
1448         // Build the tree
1450         $moodle_backup->add_child($information);
1452         $information->add_child($details);
1453         $details->add_child($detail);
1455         $information->add_child($contents);
1456         if (!empty($cinfo['activities'])) {
1457             $contents->add_child($activities);
1458             $activities->add_child($activity);
1459         }
1460         if (!empty($cinfo['sections'])) {
1461             $contents->add_child($sections);
1462             $sections->add_child($section);
1463         }
1464         if (!empty($cinfo['course'])) {
1465             $contents->add_child($course);
1466         }
1468         $information->add_child($settings);
1469         $settings->add_child($setting);
1472         // Set the sources
1474         $information->set_source_array(array((object)$info));
1476         $detail->set_source_array($dinfo);
1478         $activity->set_source_array($cinfo['activities']);
1480         $section->set_source_array($cinfo['sections']);
1482         $course->set_source_array($cinfo['course']);
1484         $setting->set_source_array($sinfo);
1486         // Prepare some information to be sent to main moodle_backup.xml file
1487         return $moodle_backup;
1488     }
1492 /**
1493  * Execution step that will generate the final zip (.mbz) file with all the contents
1494  */
1495 class backup_zip_contents extends backup_execution_step {
1497     protected function define_execution() {
1499         // Get basepath
1500         $basepath = $this->get_basepath();
1502         // Get the list of files in directory
1503         $filestemp = get_directory_list($basepath, '', false, true, true);
1504         $files = array();
1505         foreach ($filestemp as $file) { // Add zip paths and fs paths to all them
1506             $files[$file] = $basepath . '/' . $file;
1507         }
1509         // Add the log file if exists
1510         $logfilepath = $basepath . '.log';
1511         if (file_exists($logfilepath)) {
1512              $files['moodle_backup.log'] = $logfilepath;
1513         }
1515         // Calculate the zip fullpath (in OS temp area it's always backup.mbz)
1516         $zipfile = $basepath . '/backup.mbz';
1518         // Get the zip packer
1519         $zippacker = get_file_packer('application/zip');
1521         // Zip files
1522         $zippacker->archive_to_pathname($files, $zipfile);
1523     }
1526 /**
1527  * This step will send the generated backup file to its final destination
1528  */
1529 class backup_store_backup_file extends backup_execution_step {
1531     protected function define_execution() {
1533         // Get basepath
1534         $basepath = $this->get_basepath();
1536         // Calculate the zip fullpath (in OS temp area it's always backup.mbz)
1537         $zipfile = $basepath . '/backup.mbz';
1539         // Perform storage and return it (TODO: shouldn't be array but proper result object)
1540         return array('backup_destination' => backup_helper::store_backup_file($this->get_backupid(), $zipfile));
1541     }
1545 /**
1546  * This step will search for all the activity (not calculations, categories nor aggregations) grade items
1547  * and put them to the backup_ids tables, to be used later as base to backup them
1548  */
1549 class backup_activity_grade_items_to_ids extends backup_execution_step {
1551     protected function define_execution() {
1553         // Fetch all activity grade items
1554         if ($items = grade_item::fetch_all(array(
1555                          'itemtype' => 'mod', 'itemmodule' => $this->task->get_modulename(),
1556                          'iteminstance' => $this->task->get_activityid(), 'courseid' => $this->task->get_courseid()))) {
1557             // Annotate them in backup_ids
1558             foreach ($items as $item) {
1559                 backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), 'grade_item', $item->id);
1560             }
1561         }
1562     }
1565 /**
1566  * This step will annotate all the groups belonging to already annotated groupings
1567  */
1568 class backup_annotate_groups_from_groupings extends backup_execution_step {
1570     protected function define_execution() {
1571         global $DB;
1573         // Fetch all the annotated groupings
1574         if ($groupings = $DB->get_records('backup_ids_temp', array(
1575                 'backupid' => $this->get_backupid(), 'itemname' => 'grouping'))) {
1576             foreach ($groupings as $grouping) {
1577                 if ($groups = $DB->get_records('groupings_groups', array(
1578                         'groupingid' => $grouping->itemid))) {
1579                     foreach ($groups as $group) {
1580                         backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), 'group', $group->groupid);
1581                     }
1582                 }
1583             }
1584         }
1585     }
1588 /**
1589  * This step will annotate all the scales belonging to already annotated outcomes
1590  */
1591 class backup_annotate_scales_from_outcomes extends backup_execution_step {
1593     protected function define_execution() {
1594         global $DB;
1596         // Fetch all the annotated outcomes
1597         if ($outcomes = $DB->get_records('backup_ids_temp', array(
1598                 'backupid' => $this->get_backupid(), 'itemname' => 'outcome'))) {
1599             foreach ($outcomes as $outcome) {
1600                 if ($scale = $DB->get_record('grade_outcomes', array(
1601                         'id' => $outcome->itemid))) {
1602                     // Annotate as scalefinal because it's > 0
1603                     backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), 'scalefinal', $scale->scaleid);
1604                 }
1605             }
1606         }
1607     }
1610 /**
1611  * This step will generate all the file annotations for the already
1612  * annotated (final) question_categories. It calculates the different
1613  * contexts that are being backup and, annotates all the files
1614  * on every context belonging to the "question" component. As far as
1615  * we are always including *complete* question banks it is safe and
1616  * optimal to do that in this (one pass) way
1617  */
1618 class backup_annotate_all_question_files extends backup_execution_step {
1620     protected function define_execution() {
1621         global $DB;
1623         // Get all the different contexts for the final question_categories
1624         // annotated along the whole backup
1625         $rs = $DB->get_recordset_sql("SELECT DISTINCT qc.contextid
1626                                         FROM {question_categories} qc
1627                                         JOIN {backup_ids_temp} bi ON bi.itemid = qc.id
1628                                        WHERE bi.backupid = ?
1629                                          AND bi.itemname = 'question_categoryfinal'", array($this->get_backupid()));
1630         // To know about qtype specific components/fileareas
1631         $components = backup_qtype_plugin::get_components_and_fileareas();
1632         // Let's loop
1633         foreach($rs as $record) {
1634             // We don't need to specify filearea nor itemid as far as by
1635             // component and context it's enough to annotate the whole bank files
1636             // This backups "questiontext", "generalfeedback" and "answerfeedback" fileareas (all them
1637             // belonging to the "question" component
1638             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', null, null);
1639             // Again, it is enough to pick files only by context and component
1640             // Do it for qtype specific components
1641             foreach ($components as $component => $fileareas) {
1642                 backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, $component, null, null);
1643             }
1644         }
1645         $rs->close();
1646     }
1649 /**
1650  * structure step in charge of constructing the questions.xml file for all the
1651  * question categories and questions required by the backup
1652  * and letters related to one activity
1653  */
1654 class backup_questions_structure_step extends backup_structure_step {
1656     protected function define_structure() {
1658         // Define each element separated
1660         $qcategories = new backup_nested_element('question_categories');
1662         $qcategory = new backup_nested_element('question_category', array('id'), array(
1663             'name', 'contextid', 'contextlevel', 'contextinstanceid',
1664             'info', 'infoformat', 'stamp', 'parent',
1665             'sortorder'));
1667         $questions = new backup_nested_element('questions');
1669         $question = new backup_nested_element('question', array('id'), array(
1670             'parent', 'name', 'questiontext', 'questiontextformat',
1671             'generalfeedback', 'generalfeedbackformat', 'defaultmark', 'penalty',
1672             'qtype', 'length', 'stamp', 'version',
1673             'hidden', 'timecreated', 'timemodified', 'createdby', 'modifiedby'));
1675         // attach qtype plugin structure to $question element, only one allowed
1676         $this->add_plugin_structure('qtype', $question, false);
1678         $qhints = new backup_nested_element('question_hints');
1680         $qhint = new backup_nested_element('question_hint', array('id'), array(
1681             'hint', 'hintformat', 'shownumcorrect', 'clearwrong', 'options'));
1683         // Build the tree
1685         $qcategories->add_child($qcategory);
1686         $qcategory->add_child($questions);
1687         $questions->add_child($question);
1688         $question->add_child($qhints);
1689         $qhints->add_child($qhint);
1691         // Define the sources
1693         $qcategory->set_source_sql("
1694             SELECT gc.*, contextlevel, instanceid AS contextinstanceid
1695               FROM {question_categories} gc
1696               JOIN {backup_ids_temp} bi ON bi.itemid = gc.id
1697               JOIN {context} co ON co.id = gc.contextid
1698              WHERE bi.backupid = ?
1699                AND bi.itemname = 'question_categoryfinal'", array(backup::VAR_BACKUPID));
1701         $question->set_source_table('question', array('category' => backup::VAR_PARENTID));
1703         $qhint->set_source_sql('
1704                 SELECT *
1705                 FROM {question_hints}
1706                 WHERE questionid = :questionid
1707                 ORDER BY id',
1708                 array('questionid' => backup::VAR_PARENTID));
1710         // don't need to annotate ids nor files
1711         // (already done by {@link backup_annotate_all_question_files}
1713         return $qcategories;
1714     }
1719 /**
1720  * This step will generate all the file  annotations for the already
1721  * annotated (final) users. Need to do this here because each user
1722  * has its own context and structure tasks only are able to handle
1723  * one context. Also, this step will guarantee that every user has
1724  * its context created (req for other steps)
1725  */
1726 class backup_annotate_all_user_files extends backup_execution_step {
1728     protected function define_execution() {
1729         global $DB;
1731         // List of fileareas we are going to annotate
1732         $fileareas = array('profile', 'icon');
1734         if ($this->get_setting_value('user_files')) { // private files only if enabled in settings
1735             $fileareas[] = 'private';
1736         }
1738         // Fetch all annotated (final) users
1739         $rs = $DB->get_recordset('backup_ids_temp', array(
1740             'backupid' => $this->get_backupid(), 'itemname' => 'userfinal'));
1741         foreach ($rs as $record) {
1742             $userid = $record->itemid;
1743             $userctxid = get_context_instance(CONTEXT_USER, $userid)->id;
1744             // Proceed with every user filearea
1745             foreach ($fileareas as $filearea) {
1746                 // We don't need to specify itemid ($userid - 5th param) as far as by
1747                 // context we can get all the associated files. See MDL-22092
1748                 backup_structure_dbops::annotate_files($this->get_backupid(), $userctxid, 'user', $filearea, null);
1749             }
1750         }
1751         $rs->close();
1752     }
1755 /**
1756  * structure step in charge of constructing the grades.xml file for all the grade items
1757  * and letters related to one activity
1758  */
1759 class backup_activity_grades_structure_step extends backup_structure_step {
1761     protected function define_structure() {
1763         // To know if we are including userinfo
1764         $userinfo = $this->get_setting_value('userinfo');
1766         // Define each element separated
1768         $book = new backup_nested_element('activity_gradebook');
1770         $items = new backup_nested_element('grade_items');
1772         $item = new backup_nested_element('grade_item', array('id'), array(
1773             'categoryid', 'itemname', 'itemtype', 'itemmodule',
1774             'iteminstance', 'itemnumber', 'iteminfo', 'idnumber',
1775             'calculation', 'gradetype', 'grademax', 'grademin',
1776             'scaleid', 'outcomeid', 'gradepass', 'multfactor',
1777             'plusfactor', 'aggregationcoef', 'sortorder', 'display',
1778             'decimals', 'hidden', 'locked', 'locktime',
1779             'needsupdate', 'timecreated', 'timemodified'));
1781         $grades = new backup_nested_element('grade_grades');
1783         $grade = new backup_nested_element('grade_grade', array('id'), array(
1784             'userid', 'rawgrade', 'rawgrademax', 'rawgrademin',
1785             'rawscaleid', 'usermodified', 'finalgrade', 'hidden',
1786             'locked', 'locktime', 'exported', 'overridden',
1787             'excluded', 'feedback', 'feedbackformat', 'information',
1788             'informationformat', 'timecreated', 'timemodified'));
1790         $letters = new backup_nested_element('grade_letters');
1792         $letter = new backup_nested_element('grade_letter', 'id', array(
1793             'lowerboundary', 'letter'));
1795         // Build the tree
1797         $book->add_child($items);
1798         $items->add_child($item);
1800         $item->add_child($grades);
1801         $grades->add_child($grade);
1803         $book->add_child($letters);
1804         $letters->add_child($letter);
1806         // Define sources
1808         $item->set_source_sql("SELECT gi.*
1809                                FROM {grade_items} gi
1810                                JOIN {backup_ids_temp} bi ON gi.id = bi.itemid
1811                                WHERE bi.backupid = ?
1812                                AND bi.itemname = 'grade_item'", array(backup::VAR_BACKUPID));
1814         // This only happens if we are including user info
1815         if ($userinfo) {
1816             $grade->set_source_table('grade_grades', array('itemid' => backup::VAR_PARENTID));
1817         }
1819         $letter->set_source_table('grade_letters', array('contextid' => backup::VAR_CONTEXTID));
1821         // Annotations
1823         $item->annotate_ids('scalefinal', 'scaleid'); // Straight as scalefinal because it's > 0
1824         $item->annotate_ids('outcome', 'outcomeid');
1826         $grade->annotate_ids('user', 'userid');
1827         $grade->annotate_ids('user', 'usermodified');
1829         // Return the root element (book)
1831         return $book;
1832     }
1835 /**
1836  * Backups up the course completion information for the course.
1837  */
1838 class backup_course_completion_structure_step extends backup_structure_step {
1840     protected function execute_condition() {
1841         // Check that all activities have been included
1842         if ($this->task->is_excluding_activities()) {
1843             return false;
1844         }
1845         return true;
1846     }
1848     /**
1849      * The structure of the course completion backup
1850      *
1851      * @return backup_nested_element
1852      */
1853     protected function define_structure() {
1855         // To know if we are including user completion info
1856         $userinfo = $this->get_setting_value('userscompletion');
1858         $cc = new backup_nested_element('course_completion');
1860         $criteria = new backup_nested_element('course_completion_criteria', array('id'), array(
1861             'course','criteriatype', 'module', 'moduleinstance', 'courseinstanceshortname', 'enrolperiod', 'timeend', 'gradepass', 'role'
1862         ));
1864         $criteriacompletions = new backup_nested_element('course_completion_crit_completions');
1866         $criteriacomplete = new backup_nested_element('course_completion_crit_compl', array('id'), array(
1867             'criteriaid', 'userid','gradefinal','unenrolled','deleted','timecompleted'
1868         ));
1870         $coursecompletions = new backup_nested_element('course_completions', array('id'), array(
1871             'userid', 'course', 'deleted', 'timenotified', 'timeenrolled','timestarted','timecompleted','reaggregate'
1872         ));
1874         $notify = new backup_nested_element('course_completion_notify', array('id'), array(
1875             'course','role','message','timesent'
1876         ));
1878         $aggregatemethod = new backup_nested_element('course_completion_aggr_methd', array('id'), array(
1879             'course','criteriatype','method','value'
1880         ));
1882         $cc->add_child($criteria);
1883             $criteria->add_child($criteriacompletions);
1884                 $criteriacompletions->add_child($criteriacomplete);
1885         $cc->add_child($coursecompletions);
1886         $cc->add_child($notify);
1887         $cc->add_child($aggregatemethod);
1889         // We need to get the courseinstances shortname rather than an ID for restore
1890         $criteria->set_source_sql("SELECT ccc.*, c.shortname AS courseinstanceshortname
1891                                    FROM {course_completion_criteria} ccc
1892                                    LEFT JOIN {course} c ON c.id = ccc.courseinstance
1893                                    WHERE ccc.course = ?", array(backup::VAR_COURSEID));
1896         $notify->set_source_table('course_completion_notify', array('course' => backup::VAR_COURSEID));
1897         $aggregatemethod->set_source_table('course_completion_aggr_methd', array('course' => backup::VAR_COURSEID));
1899         if ($userinfo) {
1900             $criteriacomplete->set_source_table('course_completion_crit_compl', array('criteriaid' => backup::VAR_PARENTID));
1901             $coursecompletions->set_source_table('course_completions', array('course' => backup::VAR_COURSEID));
1902         }
1904         $criteria->annotate_ids('role', 'role');
1905         $criteriacomplete->annotate_ids('user', 'userid');
1906         $coursecompletions->annotate_ids('user', 'userid');
1907         $notify->annotate_ids('role', 'role');
1909         return $cc;
1911     }