MDL-57898 core_course: backup/restore support for course custom fields
[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  * Defines various backup steps that will be used by common tasks in backup
20  *
21  * @package     core_backup
22  * @subpackage  moodle2
23  * @category    backup
24  * @copyright   2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
25  * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  */
28 defined('MOODLE_INTERNAL') || die();
30 /**
31  * Create the temp dir where backup/restore will happen and create temp ids table.
32  */
33 class create_and_clean_temp_stuff extends backup_execution_step {
35     protected function define_execution() {
36         $progress = $this->task->get_progress();
37         $progress->start_progress('Deleting backup directories');
38         backup_helper::check_and_create_backup_dir($this->get_backupid());// Create backup temp dir
39         backup_helper::clear_backup_dir($this->get_backupid(), $progress);           // Empty temp dir, just in case
40         backup_controller_dbops::drop_backup_ids_temp_table($this->get_backupid()); // Drop ids temp table
41         backup_controller_dbops::create_backup_ids_temp_table($this->get_backupid()); // Create ids temp table
42         $progress->end_progress();
43     }
44 }
46 /**
47  * Delete the temp dir used by backup/restore (conditionally),
48  * delete old directories and drop temp ids table. Note we delete
49  * the directory but not the corresponding log file that will be
50  * there for, at least, 1 week - only delete_old_backup_dirs() or cron
51  * deletes log files (for easier access to them).
52  */
53 class drop_and_clean_temp_stuff extends backup_execution_step {
55     protected $skipcleaningtempdir = false;
57     protected function define_execution() {
58         global $CFG;
60         backup_controller_dbops::drop_backup_ids_temp_table($this->get_backupid()); // Drop ids temp table
61         backup_helper::delete_old_backup_dirs(strtotime('-1 week'));                // Delete > 1 week old temp dirs.
62         // Delete temp dir conditionally:
63         // 1) If $CFG->keeptempdirectoriesonbackup is not enabled
64         // 2) If backup temp dir deletion has been marked to be avoided
65         if (empty($CFG->keeptempdirectoriesonbackup) && !$this->skipcleaningtempdir) {
66             $progress = $this->task->get_progress();
67             $progress->start_progress('Deleting backup dir');
68             backup_helper::delete_backup_dir($this->get_backupid(), $progress); // Empty backup dir
69             $progress->end_progress();
70         }
71     }
73     public function skip_cleaning_temp_dir($skip) {
74         $this->skipcleaningtempdir = $skip;
75     }
76 }
78 /**
79  * Create the directory where all the task (activity/block...) information will be stored
80  */
81 class create_taskbasepath_directory extends backup_execution_step {
83     protected function define_execution() {
84         global $CFG;
85         $basepath = $this->task->get_taskbasepath();
86         if (!check_dir_exists($basepath, true, true)) {
87             throw new backup_step_exception('cannot_create_taskbasepath_directory', $basepath);
88         }
89     }
90 }
92 /**
93  * Abstract structure step, parent of all the activity structure steps. Used to wrap the
94  * activity structure definition within the main <activity ...> tag.
95  */
96 abstract class backup_activity_structure_step extends backup_structure_step {
98     /**
99      * Wraps any activity backup structure within the common 'activity' element
100      * that will include common to all activities information like id, context...
101      *
102      * @param backup_nested_element $activitystructure the element to wrap
103      * @return backup_nested_element the $activitystructure wrapped by the common 'activity' element
104      */
105     protected function prepare_activity_structure($activitystructure) {
107         // Create the wrap element
108         $activity = new backup_nested_element('activity', array('id', 'moduleid', 'modulename', 'contextid'), null);
110         // Build the tree
111         $activity->add_child($activitystructure);
113         // Set the source
114         $activityarr = array((object)array(
115             'id'         => $this->task->get_activityid(),
116             'moduleid'   => $this->task->get_moduleid(),
117             'modulename' => $this->task->get_modulename(),
118             'contextid'  => $this->task->get_contextid()));
120         $activity->set_source_array($activityarr);
122         // Return the root element (activity)
123         return $activity;
124     }
127 /**
128  * Abstract structure step, to be used by all the activities using core questions stuff
129  * (namely quiz module), supporting question plugins, states and sessions
130  */
131 abstract class backup_questions_activity_structure_step extends backup_activity_structure_step {
133     /**
134      * Attach to $element (usually attempts) the needed backup structures
135      * for question_usages and all the associated data.
136      *
137      * @param backup_nested_element $element the element that will contain all the question_usages data.
138      * @param string $usageidname the name of the element that holds the usageid.
139      *      This must be child of $element, and must be a final element.
140      * @param string $nameprefix this prefix is added to all the element names we create.
141      *      Element names in the XML must be unique, so if you are using usages in
142      *      two different ways, you must give a prefix to at least one of them. If
143      *      you only use one sort of usage, then you can just use the default empty prefix.
144      *      This should include a trailing underscore. For example "myprefix_"
145      */
146     protected function add_question_usages($element, $usageidname, $nameprefix = '') {
147         global $CFG;
148         require_once($CFG->dirroot . '/question/engine/lib.php');
150         // Check $element is one nested_backup_element
151         if (! $element instanceof backup_nested_element) {
152             throw new backup_step_exception('question_states_bad_parent_element', $element);
153         }
154         if (! $element->get_final_element($usageidname)) {
155             throw new backup_step_exception('question_states_bad_question_attempt_element', $usageidname);
156         }
158         $quba = new backup_nested_element($nameprefix . 'question_usage', array('id'),
159                 array('component', 'preferredbehaviour'));
161         $qas = new backup_nested_element($nameprefix . 'question_attempts');
162         $qa = new backup_nested_element($nameprefix . 'question_attempt', array('id'), array(
163                 'slot', 'behaviour', 'questionid', 'variant', 'maxmark', 'minfraction', 'maxfraction',
164                 'flagged', 'questionsummary', 'rightanswer', 'responsesummary',
165                 'timemodified'));
167         $steps = new backup_nested_element($nameprefix . 'steps');
168         $step = new backup_nested_element($nameprefix . 'step', array('id'), array(
169                 'sequencenumber', 'state', 'fraction', 'timecreated', 'userid'));
171         $response = new backup_nested_element($nameprefix . 'response');
172         $variable = new backup_nested_element($nameprefix . 'variable', null,  array('name', 'value'));
174         // Build the tree
175         $element->add_child($quba);
176         $quba->add_child($qas);
177         $qas->add_child($qa);
178         $qa->add_child($steps);
179         $steps->add_child($step);
180         $step->add_child($response);
181         $response->add_child($variable);
183         // Set the sources
184         $quba->set_source_table('question_usages',
185                 array('id'                => '../' . $usageidname));
186         $qa->set_source_table('question_attempts', array('questionusageid' => backup::VAR_PARENTID), 'slot ASC');
187         $step->set_source_table('question_attempt_steps', array('questionattemptid' => backup::VAR_PARENTID), 'sequencenumber ASC');
188         $variable->set_source_table('question_attempt_step_data', array('attemptstepid' => backup::VAR_PARENTID));
190         // Annotate ids
191         $qa->annotate_ids('question', 'questionid');
192         $step->annotate_ids('user', 'userid');
194         // Annotate files
195         $fileareas = question_engine::get_all_response_file_areas();
196         foreach ($fileareas as $filearea) {
197             $step->annotate_files('question', $filearea, 'id');
198         }
199     }
203 /**
204  * backup structure step in charge of calculating the categories to be
205  * included in backup, based in the context being backuped (module/course)
206  * and the already annotated questions present in backup_ids_temp
207  */
208 class backup_calculate_question_categories extends backup_execution_step {
210     protected function define_execution() {
211         backup_question_dbops::calculate_question_categories($this->get_backupid(), $this->task->get_contextid());
212     }
215 /**
216  * backup structure step in charge of deleting all the questions annotated
217  * in the backup_ids_temp table
218  */
219 class backup_delete_temp_questions extends backup_execution_step {
221     protected function define_execution() {
222         backup_question_dbops::delete_temp_questions($this->get_backupid());
223     }
226 /**
227  * Abstract structure step, parent of all the block structure steps. Used to wrap the
228  * block structure definition within the main <block ...> tag
229  */
230 abstract class backup_block_structure_step extends backup_structure_step {
232     protected function prepare_block_structure($blockstructure) {
234         // Create the wrap element
235         $block = new backup_nested_element('block', array('id', 'blockname', 'contextid'), null);
237         // Build the tree
238         $block->add_child($blockstructure);
240         // Set the source
241         $blockarr = array((object)array(
242             'id'         => $this->task->get_blockid(),
243             'blockname'  => $this->task->get_blockname(),
244             'contextid'  => $this->task->get_contextid()));
246         $block->set_source_array($blockarr);
248         // Return the root element (block)
249         return $block;
250     }
253 /**
254  * structure step that will generate the module.xml file for the activity,
255  * accumulating various information about the activity, annotating groupings
256  * and completion/avail conf
257  */
258 class backup_module_structure_step extends backup_structure_step {
260     protected function define_structure() {
261         global $DB;
263         // Define each element separated
265         $module = new backup_nested_element('module', array('id', 'version'), array(
266             'modulename', 'sectionid', 'sectionnumber', 'idnumber',
267             'added', 'score', 'indent', 'visible', 'visibleoncoursepage',
268             'visibleold', 'groupmode', 'groupingid',
269             'completion', 'completiongradeitemnumber', 'completionview', 'completionexpected',
270             'availability', 'showdescription'));
272         $tags = new backup_nested_element('tags');
273         $tag = new backup_nested_element('tag', array('id'), array('name', 'rawname'));
275         // attach format plugin structure to $module element, only one allowed
276         $this->add_plugin_structure('format', $module, false);
278         // attach plagiarism plugin structure to $module element, there can be potentially
279         // many plagiarism plugins storing information about this course
280         $this->add_plugin_structure('plagiarism', $module, true);
282         // attach local plugin structure to $module, multiple allowed
283         $this->add_plugin_structure('local', $module, true);
285         // Attach admin tools plugin structure to $module.
286         $this->add_plugin_structure('tool', $module, true);
288         $module->add_child($tags);
289         $tags->add_child($tag);
291         // Set the sources
292         $concat = $DB->sql_concat("'mod_'", 'm.name');
293         $module->set_source_sql("
294             SELECT cm.*, cp.value AS version, m.name AS modulename, s.id AS sectionid, s.section AS sectionnumber
295               FROM {course_modules} cm
296               JOIN {modules} m ON m.id = cm.module
297               JOIN {config_plugins} cp ON cp.plugin = $concat AND cp.name = 'version'
298               JOIN {course_sections} s ON s.id = cm.section
299              WHERE cm.id = ?", array(backup::VAR_MODID));
301         $tag->set_source_sql("SELECT t.id, t.name, t.rawname
302                                 FROM {tag} t
303                                 JOIN {tag_instance} ti ON ti.tagid = t.id
304                                WHERE ti.itemtype = 'course_modules'
305                                  AND ti.component = 'core'
306                                  AND ti.itemid = ?", array(backup::VAR_MODID));
308         // Define annotations
309         $module->annotate_ids('grouping', 'groupingid');
311         // Return the root element ($module)
312         return $module;
313     }
316 /**
317  * structure step that will generate the section.xml file for the section
318  * annotating files
319  */
320 class backup_section_structure_step extends backup_structure_step {
322     protected function define_structure() {
324         // Define each element separated
326         $section = new backup_nested_element('section', array('id'), array(
327                 'number', 'name', 'summary', 'summaryformat', 'sequence', 'visible',
328                 'availabilityjson', 'timemodified'));
330         // attach format plugin structure to $section element, only one allowed
331         $this->add_plugin_structure('format', $section, false);
333         // attach local plugin structure to $section element, multiple allowed
334         $this->add_plugin_structure('local', $section, true);
336         // Add nested elements for course_format_options table
337         $formatoptions = new backup_nested_element('course_format_options', array('id'), array(
338             'format', 'name', 'value'));
339         $section->add_child($formatoptions);
341         // Define sources.
342         $section->set_source_table('course_sections', array('id' => backup::VAR_SECTIONID));
343         $formatoptions->set_source_sql('SELECT cfo.id, cfo.format, cfo.name, cfo.value
344               FROM {course} c
345               JOIN {course_format_options} cfo
346               ON cfo.courseid = c.id AND cfo.format = c.format
347               WHERE c.id = ? AND cfo.sectionid = ?',
348                 array(backup::VAR_COURSEID, backup::VAR_SECTIONID));
350         // Aliases
351         $section->set_source_alias('section', 'number');
352         // The 'availability' field needs to be renamed because it clashes with
353         // the old nested element structure for availability data.
354         $section->set_source_alias('availability', 'availabilityjson');
356         // Set annotations
357         $section->annotate_files('course', 'section', 'id');
359         return $section;
360     }
363 /**
364  * structure step that will generate the course.xml file for the course, including
365  * course category reference, tags, modules restriction information
366  * and some annotations (files & groupings)
367  */
368 class backup_course_structure_step extends backup_structure_step {
370     protected function define_structure() {
371         global $DB;
373         // Define each element separated
375         $course = new backup_nested_element('course', array('id', 'contextid'), array(
376             'shortname', 'fullname', 'idnumber',
377             'summary', 'summaryformat', 'format', 'showgrades',
378             'newsitems', 'startdate', 'enddate',
379             'marker', 'maxbytes', 'legacyfiles', 'showreports',
380             'visible', 'groupmode', 'groupmodeforce',
381             'defaultgroupingid', 'lang', 'theme',
382             'timecreated', 'timemodified',
383             'requested',
384             'enablecompletion', 'completionstartonenrol', 'completionnotify'));
386         $category = new backup_nested_element('category', array('id'), array(
387             'name', 'description'));
389         $tags = new backup_nested_element('tags');
391         $tag = new backup_nested_element('tag', array('id'), array(
392             'name', 'rawname'));
394         $customfields = new backup_nested_element('customfields');
395         $customfield = new backup_nested_element('customfield', array('id'), array(
396           'shortname', 'type', 'value', 'valueformat'
397         ));
399         // attach format plugin structure to $course element, only one allowed
400         $this->add_plugin_structure('format', $course, false);
402         // attach theme plugin structure to $course element; multiple themes can
403         // save course data (in case of user theme, legacy theme, etc)
404         $this->add_plugin_structure('theme', $course, true);
406         // attach general report plugin structure to $course element; multiple
407         // reports can save course data if required
408         $this->add_plugin_structure('report', $course, true);
410         // attach course report plugin structure to $course element; multiple
411         // course reports can save course data if required
412         $this->add_plugin_structure('coursereport', $course, true);
414         // attach plagiarism plugin structure to $course element, there can be potentially
415         // many plagiarism plugins storing information about this course
416         $this->add_plugin_structure('plagiarism', $course, true);
418         // attach local plugin structure to $course element; multiple local plugins
419         // can save course data if required
420         $this->add_plugin_structure('local', $course, true);
422         // Attach admin tools plugin structure to $course element; multiple plugins
423         // can save course data if required.
424         $this->add_plugin_structure('tool', $course, true);
426         // Build the tree
428         $course->add_child($category);
430         $course->add_child($tags);
431         $tags->add_child($tag);
433         $course->add_child($customfields);
434         $customfields->add_child($customfield);
436         // Set the sources
438         $courserec = $DB->get_record('course', array('id' => $this->task->get_courseid()));
439         $courserec->contextid = $this->task->get_contextid();
441         $formatoptions = course_get_format($courserec)->get_format_options();
442         $course->add_final_elements(array_keys($formatoptions));
443         foreach ($formatoptions as $key => $value) {
444             $courserec->$key = $value;
445         }
447         // Add 'numsections' in order to be able to restore in previous versions of Moodle.
448         // Even though Moodle does not officially support restore into older verions of Moodle from the
449         // version where backup was made, without 'numsections' restoring will go very wrong.
450         if (!property_exists($courserec, 'numsections') && course_get_format($courserec)->uses_sections()) {
451             $courserec->numsections = course_get_format($courserec)->get_last_section_number();
452         }
454         $course->set_source_array(array($courserec));
456         $categoryrec = $DB->get_record('course_categories', array('id' => $courserec->category));
458         $category->set_source_array(array($categoryrec));
460         $tag->set_source_sql('SELECT t.id, t.name, t.rawname
461                                 FROM {tag} t
462                                 JOIN {tag_instance} ti ON ti.tagid = t.id
463                                WHERE ti.itemtype = ?
464                                  AND ti.itemid = ?', array(
465                                      backup_helper::is_sqlparam('course'),
466                                      backup::VAR_PARENTID));
468         $handler = core_course\customfield\course_handler::create();
469         $fieldsforbackup = $handler->get_instance_data_for_backup($this->task->get_courseid());
470         $customfield->set_source_array($fieldsforbackup);
472         // Some annotations
474         $course->annotate_ids('grouping', 'defaultgroupingid');
476         $course->annotate_files('course', 'summary', null);
477         $course->annotate_files('course', 'overviewfiles', null);
478         $course->annotate_files('course', 'legacy', null);
480         // Return root element ($course)
482         return $course;
483     }
486 /**
487  * structure step that will generate the enrolments.xml file for the given course
488  */
489 class backup_enrolments_structure_step extends backup_structure_step {
491     /**
492      * Skip enrolments on the front page.
493      * @return bool
494      */
495     protected function execute_condition() {
496         return ($this->get_courseid() != SITEID);
497     }
499     protected function define_structure() {
501         // To know if we are including users
502         $users = $this->get_setting_value('users');
504         // Define each element separated
506         $enrolments = new backup_nested_element('enrolments');
508         $enrols = new backup_nested_element('enrols');
510         $enrol = new backup_nested_element('enrol', array('id'), array(
511             'enrol', 'status', 'name', 'enrolperiod', 'enrolstartdate',
512             'enrolenddate', 'expirynotify', 'expirythreshold', 'notifyall',
513             'password', 'cost', 'currency', 'roleid',
514             'customint1', 'customint2', 'customint3', 'customint4', 'customint5', 'customint6', 'customint7', 'customint8',
515             'customchar1', 'customchar2', 'customchar3',
516             'customdec1', 'customdec2',
517             'customtext1', 'customtext2', 'customtext3', 'customtext4',
518             'timecreated', 'timemodified'));
520         $userenrolments = new backup_nested_element('user_enrolments');
522         $enrolment = new backup_nested_element('enrolment', array('id'), array(
523             'status', 'userid', 'timestart', 'timeend', 'modifierid',
524             'timemodified'));
526         // Build the tree
527         $enrolments->add_child($enrols);
528         $enrols->add_child($enrol);
529         $enrol->add_child($userenrolments);
530         $userenrolments->add_child($enrolment);
532         // Define sources - the instances are restored using the same sortorder, we do not need to store it in xml and deal with it afterwards.
533         $enrol->set_source_table('enrol', array('courseid' => backup::VAR_COURSEID), 'sortorder ASC');
535         // User enrolments only added only if users included
536         if ($users) {
537             $enrolment->set_source_table('user_enrolments', array('enrolid' => backup::VAR_PARENTID));
538             $enrolment->annotate_ids('user', 'userid');
539         }
541         $enrol->annotate_ids('role', 'roleid');
543         // Add enrol plugin structure.
544         $this->add_plugin_structure('enrol', $enrol, true);
546         return $enrolments;
547     }
550 /**
551  * structure step that will generate the roles.xml file for the given context, observing
552  * the role_assignments setting to know if that part needs to be included
553  */
554 class backup_roles_structure_step extends backup_structure_step {
556     protected function define_structure() {
558         // To know if we are including role assignments
559         $roleassignments = $this->get_setting_value('role_assignments');
561         // Define each element separated
563         $roles = new backup_nested_element('roles');
565         $overrides = new backup_nested_element('role_overrides');
567         $override = new backup_nested_element('override', array('id'), array(
568             'roleid', 'capability', 'permission', 'timemodified',
569             'modifierid'));
571         $assignments = new backup_nested_element('role_assignments');
573         $assignment = new backup_nested_element('assignment', array('id'), array(
574             'roleid', 'userid', 'timemodified', 'modifierid', 'component', 'itemid',
575             'sortorder'));
577         // Build the tree
578         $roles->add_child($overrides);
579         $roles->add_child($assignments);
581         $overrides->add_child($override);
582         $assignments->add_child($assignment);
584         // Define sources
586         $override->set_source_table('role_capabilities', array('contextid' => backup::VAR_CONTEXTID));
588         // Assignments only added if specified
589         if ($roleassignments) {
590             $assignment->set_source_table('role_assignments', array('contextid' => backup::VAR_CONTEXTID));
591         }
593         // Define id annotations
594         $override->annotate_ids('role', 'roleid');
596         $assignment->annotate_ids('role', 'roleid');
598         $assignment->annotate_ids('user', 'userid');
600         //TODO: how do we annotate the itemid? the meaning depends on the content of component table (skodak)
602         return $roles;
603     }
606 /**
607  * structure step that will generate the roles.xml containing the
608  * list of roles used along the whole backup process. Just raw
609  * list of used roles from role table
610  */
611 class backup_final_roles_structure_step extends backup_structure_step {
613     protected function define_structure() {
615         // Define elements
617         $rolesdef = new backup_nested_element('roles_definition');
619         $role = new backup_nested_element('role', array('id'), array(
620             'name', 'shortname', 'nameincourse', 'description',
621             'sortorder', 'archetype'));
623         // Build the tree
625         $rolesdef->add_child($role);
627         // Define sources
629         $role->set_source_sql("SELECT r.*, rn.name AS nameincourse
630                                  FROM {role} r
631                                  JOIN {backup_ids_temp} bi ON r.id = bi.itemid
632                             LEFT JOIN {role_names} rn ON r.id = rn.roleid AND rn.contextid = ?
633                                 WHERE bi.backupid = ?
634                                   AND bi.itemname = 'rolefinal'", array(backup::VAR_CONTEXTID, backup::VAR_BACKUPID));
636         // Return main element (rolesdef)
637         return $rolesdef;
638     }
641 /**
642  * structure step that will generate the scales.xml containing the
643  * list of scales used along the whole backup process.
644  */
645 class backup_final_scales_structure_step extends backup_structure_step {
647     protected function define_structure() {
649         // Define elements
651         $scalesdef = new backup_nested_element('scales_definition');
653         $scale = new backup_nested_element('scale', array('id'), array(
654             'courseid', 'userid', 'name', 'scale',
655             'description', 'descriptionformat', 'timemodified'));
657         // Build the tree
659         $scalesdef->add_child($scale);
661         // Define sources
663         $scale->set_source_sql("SELECT s.*
664                                   FROM {scale} s
665                                   JOIN {backup_ids_temp} bi ON s.id = bi.itemid
666                                  WHERE bi.backupid = ?
667                                    AND bi.itemname = 'scalefinal'", array(backup::VAR_BACKUPID));
669         // Annotate scale files (they store files in system context, so pass it instead of default one)
670         $scale->annotate_files('grade', 'scale', 'id', context_system::instance()->id);
672         // Return main element (scalesdef)
673         return $scalesdef;
674     }
677 /**
678  * structure step that will generate the outcomes.xml containing the
679  * list of outcomes used along the whole backup process.
680  */
681 class backup_final_outcomes_structure_step extends backup_structure_step {
683     protected function define_structure() {
685         // Define elements
687         $outcomesdef = new backup_nested_element('outcomes_definition');
689         $outcome = new backup_nested_element('outcome', array('id'), array(
690             'courseid', 'userid', 'shortname', 'fullname',
691             'scaleid', 'description', 'descriptionformat', 'timecreated',
692             'timemodified','usermodified'));
694         // Build the tree
696         $outcomesdef->add_child($outcome);
698         // Define sources
700         $outcome->set_source_sql("SELECT o.*
701                                     FROM {grade_outcomes} o
702                                     JOIN {backup_ids_temp} bi ON o.id = bi.itemid
703                                    WHERE bi.backupid = ?
704                                      AND bi.itemname = 'outcomefinal'", array(backup::VAR_BACKUPID));
706         // Annotate outcome files (they store files in system context, so pass it instead of default one)
707         $outcome->annotate_files('grade', 'outcome', 'id', context_system::instance()->id);
709         // Return main element (outcomesdef)
710         return $outcomesdef;
711     }
714 /**
715  * structure step in charge of constructing the filters.xml file for all the filters found
716  * in activity
717  */
718 class backup_filters_structure_step extends backup_structure_step {
720     protected function define_structure() {
722         // Define each element separated
724         $filters = new backup_nested_element('filters');
726         $actives = new backup_nested_element('filter_actives');
728         $active = new backup_nested_element('filter_active', null, array('filter', 'active'));
730         $configs = new backup_nested_element('filter_configs');
732         $config = new backup_nested_element('filter_config', null, array('filter', 'name', 'value'));
734         // Build the tree
736         $filters->add_child($actives);
737         $filters->add_child($configs);
739         $actives->add_child($active);
740         $configs->add_child($config);
742         // Define sources
744         list($activearr, $configarr) = filter_get_all_local_settings($this->task->get_contextid());
746         $active->set_source_array($activearr);
747         $config->set_source_array($configarr);
749         // Return the root element (filters)
750         return $filters;
751     }
754 /**
755  * structure step in charge of constructing the comments.xml file for all the comments found
756  * in a given context
757  */
758 class backup_comments_structure_step extends backup_structure_step {
760     protected function define_structure() {
762         // Define each element separated
764         $comments = new backup_nested_element('comments');
766         $comment = new backup_nested_element('comment', array('id'), array(
767             'commentarea', 'itemid', 'content', 'format',
768             'userid', 'timecreated'));
770         // Build the tree
772         $comments->add_child($comment);
774         // Define sources
776         $comment->set_source_table('comments', array('contextid' => backup::VAR_CONTEXTID));
778         // Define id annotations
780         $comment->annotate_ids('user', 'userid');
782         // Return the root element (comments)
783         return $comments;
784     }
787 /**
788  * structure step in charge of constructing the badges.xml file for all the badges found
789  * in a given context
790  */
791 class backup_badges_structure_step extends backup_structure_step {
793     protected function execute_condition() {
794         // Check that all activities have been included.
795         if ($this->task->is_excluding_activities()) {
796             return false;
797         }
798         return true;
799     }
801     protected function define_structure() {
803         // Define each element separated.
805         $badges = new backup_nested_element('badges');
806         $badge = new backup_nested_element('badge', array('id'), array('name', 'description',
807                 'timecreated', 'timemodified', 'usercreated', 'usermodified', 'issuername',
808                 'issuerurl', 'issuercontact', 'expiredate', 'expireperiod', 'type', 'courseid',
809                 'message', 'messagesubject', 'attachment', 'notification', 'status', 'nextcron'));
811         $criteria = new backup_nested_element('criteria');
812         $criterion = new backup_nested_element('criterion', array('id'), array('badgeid',
813                 'criteriatype', 'method', 'description', 'descriptionformat'));
815         $parameters = new backup_nested_element('parameters');
816         $parameter = new backup_nested_element('parameter', array('id'), array('critid',
817                 'name', 'value', 'criteriatype'));
819         $manual_awards = new backup_nested_element('manual_awards');
820         $manual_award = new backup_nested_element('manual_award', array('id'), array('badgeid',
821                 'recipientid', 'issuerid', 'issuerrole', 'datemet'));
823         // Build the tree.
825         $badges->add_child($badge);
826         $badge->add_child($criteria);
827         $criteria->add_child($criterion);
828         $criterion->add_child($parameters);
829         $parameters->add_child($parameter);
830         $badge->add_child($manual_awards);
831         $manual_awards->add_child($manual_award);
833         // Define sources.
835         $badge->set_source_table('badge', array('courseid' => backup::VAR_COURSEID));
836         $criterion->set_source_table('badge_criteria', array('badgeid' => backup::VAR_PARENTID));
838         $parametersql = 'SELECT cp.*, c.criteriatype
839                              FROM {badge_criteria_param} cp JOIN {badge_criteria} c
840                                  ON cp.critid = c.id
841                              WHERE critid = :critid';
842         $parameterparams = array('critid' => backup::VAR_PARENTID);
843         $parameter->set_source_sql($parametersql, $parameterparams);
845         $manual_award->set_source_table('badge_manual_award', array('badgeid' => backup::VAR_PARENTID));
847         // Define id annotations.
849         $badge->annotate_ids('user', 'usercreated');
850         $badge->annotate_ids('user', 'usermodified');
851         $criterion->annotate_ids('badge', 'badgeid');
852         $parameter->annotate_ids('criterion', 'critid');
853         $badge->annotate_files('badges', 'badgeimage', 'id');
854         $manual_award->annotate_ids('badge', 'badgeid');
855         $manual_award->annotate_ids('user', 'recipientid');
856         $manual_award->annotate_ids('user', 'issuerid');
857         $manual_award->annotate_ids('role', 'issuerrole');
859         // Return the root element ($badges).
860         return $badges;
861     }
864 /**
865  * structure step in charge of constructing the calender.xml file for all the events found
866  * in a given context
867  */
868 class backup_calendarevents_structure_step extends backup_structure_step {
870     protected function define_structure() {
872         // Define each element separated
874         $events = new backup_nested_element('events');
876         $event = new backup_nested_element('event', array('id'), array(
877                 'name', 'description', 'format', 'courseid', 'groupid', 'userid',
878                 'repeatid', 'modulename', 'instance', 'type', 'eventtype', 'timestart',
879                 'timeduration', 'timesort', 'visible', 'uuid', 'sequence', 'timemodified',
880                 'priority', 'location'));
882         // Build the tree
883         $events->add_child($event);
885         // Define sources
886         if ($this->name == 'course_calendar') {
887             $calendar_items_sql ="SELECT * FROM {event}
888                         WHERE courseid = :courseid
889                         AND (eventtype = 'course' OR eventtype = 'group')";
890             $calendar_items_params = array('courseid'=>backup::VAR_COURSEID);
891             $event->set_source_sql($calendar_items_sql, $calendar_items_params);
892         } else if ($this->name == 'activity_calendar') {
893             // We don't backup action events.
894             $params = array('instance' => backup::VAR_ACTIVITYID, 'modulename' => backup::VAR_MODNAME,
895                 'type' => array('sqlparam' => CALENDAR_EVENT_TYPE_ACTION));
896             // If we don't want to include the userinfo in the backup then setting the courseid
897             // will filter out all of the user override events (which have a course id of zero).
898             $coursewhere = "";
899             if (!$this->get_setting_value('userinfo')) {
900                 $params['courseid'] = backup::VAR_COURSEID;
901                 $coursewhere = " AND courseid = :courseid";
902             }
903             $calendarsql = "SELECT * FROM {event}
904                              WHERE instance = :instance
905                                AND type <> :type
906                                AND modulename = :modulename";
907             $calendarsql = $calendarsql . $coursewhere;
908             $event->set_source_sql($calendarsql, $params);
909         } else {
910             $event->set_source_table('event', array('courseid' => backup::VAR_COURSEID, 'instance' => backup::VAR_ACTIVITYID, 'modulename' => backup::VAR_MODNAME));
911         }
913         // Define id annotations
915         $event->annotate_ids('user', 'userid');
916         $event->annotate_ids('group', 'groupid');
917         $event->annotate_files('calendar', 'event_description', 'id');
919         // Return the root element (events)
920         return $events;
921     }
924 /**
925  * structure step in charge of constructing the gradebook.xml file for all the gradebook config in the course
926  * NOTE: the backup of the grade items themselves is handled by backup_activity_grades_structure_step
927  */
928 class backup_gradebook_structure_step extends backup_structure_step {
930     /**
931      * We need to decide conditionally, based on dynamic information
932      * about the execution of this step. Only will be executed if all
933      * the module gradeitems have been already included in backup
934      */
935     protected function execute_condition() {
936         $courseid = $this->get_courseid();
937         if ($courseid == SITEID) {
938             return false;
939         }
941         return backup_plan_dbops::require_gradebook_backup($courseid, $this->get_backupid());
942     }
944     protected function define_structure() {
945         global $CFG, $DB;
947         // are we including user info?
948         $userinfo = $this->get_setting_value('users');
950         $gradebook = new backup_nested_element('gradebook');
952         //grade_letters are done in backup_activity_grades_structure_step()
954         //calculated grade items
955         $grade_items = new backup_nested_element('grade_items');
956         $grade_item = new backup_nested_element('grade_item', array('id'), array(
957             'categoryid', 'itemname', 'itemtype', 'itemmodule',
958             'iteminstance', 'itemnumber', 'iteminfo', 'idnumber',
959             'calculation', 'gradetype', 'grademax', 'grademin',
960             'scaleid', 'outcomeid', 'gradepass', 'multfactor',
961             'plusfactor', 'aggregationcoef', 'aggregationcoef2', 'weightoverride',
962             'sortorder', 'display', 'decimals', 'hidden', 'locked', 'locktime',
963             'needsupdate', 'timecreated', 'timemodified'));
965         $grade_grades = new backup_nested_element('grade_grades');
966         $grade_grade = new backup_nested_element('grade_grade', array('id'), array(
967             'userid', 'rawgrade', 'rawgrademax', 'rawgrademin',
968             'rawscaleid', 'usermodified', 'finalgrade', 'hidden',
969             'locked', 'locktime', 'exported', 'overridden',
970             'excluded', 'feedback', 'feedbackformat', 'information',
971             'informationformat', 'timecreated', 'timemodified',
972             'aggregationstatus', 'aggregationweight'));
974         //grade_categories
975         $grade_categories = new backup_nested_element('grade_categories');
976         $grade_category   = new backup_nested_element('grade_category', array('id'), array(
977                 //'courseid',
978                 'parent', 'depth', 'path', 'fullname', 'aggregation', 'keephigh',
979                 'droplow', 'aggregateonlygraded', 'aggregateoutcomes',
980                 'timecreated', 'timemodified', 'hidden'));
982         $letters = new backup_nested_element('grade_letters');
983         $letter = new backup_nested_element('grade_letter', 'id', array(
984             'lowerboundary', 'letter'));
986         $grade_settings = new backup_nested_element('grade_settings');
987         $grade_setting = new backup_nested_element('grade_setting', 'id', array(
988             'name', 'value'));
990         $gradebook_attributes = new backup_nested_element('attributes', null, array('calculations_freeze'));
992         // Build the tree
993         $gradebook->add_child($gradebook_attributes);
995         $gradebook->add_child($grade_categories);
996         $grade_categories->add_child($grade_category);
998         $gradebook->add_child($grade_items);
999         $grade_items->add_child($grade_item);
1000         $grade_item->add_child($grade_grades);
1001         $grade_grades->add_child($grade_grade);
1003         $gradebook->add_child($letters);
1004         $letters->add_child($letter);
1006         $gradebook->add_child($grade_settings);
1007         $grade_settings->add_child($grade_setting);
1009         // Define sources
1011         // Add attribute with gradebook calculation freeze date if needed.
1012         $attributes = new stdClass();
1013         $gradebookcalculationfreeze = get_config('core', 'gradebook_calculations_freeze_' . $this->get_courseid());
1014         if ($gradebookcalculationfreeze) {
1015             $attributes->calculations_freeze = $gradebookcalculationfreeze;
1016         }
1017         $gradebook_attributes->set_source_array([$attributes]);
1019         //Include manual, category and the course grade item
1020         $grade_items_sql ="SELECT * FROM {grade_items}
1021                            WHERE courseid = :courseid
1022                            AND (itemtype='manual' OR itemtype='course' OR itemtype='category')";
1023         $grade_items_params = array('courseid'=>backup::VAR_COURSEID);
1024         $grade_item->set_source_sql($grade_items_sql, $grade_items_params);
1026         if ($userinfo) {
1027             $grade_grade->set_source_table('grade_grades', array('itemid' => backup::VAR_PARENTID));
1028         }
1030         $grade_category_sql = "SELECT gc.*, gi.sortorder
1031                                FROM {grade_categories} gc
1032                                JOIN {grade_items} gi ON (gi.iteminstance = gc.id)
1033                                WHERE gc.courseid = :courseid
1034                                AND (gi.itemtype='course' OR gi.itemtype='category')
1035                                ORDER BY gc.parent ASC";//need parent categories before their children
1036         $grade_category_params = array('courseid'=>backup::VAR_COURSEID);
1037         $grade_category->set_source_sql($grade_category_sql, $grade_category_params);
1039         $letter->set_source_table('grade_letters', array('contextid' => backup::VAR_CONTEXTID));
1041         // Set the grade settings source, forcing the inclusion of minmaxtouse if not present.
1042         $settings = array();
1043         $rs = $DB->get_recordset('grade_settings', array('courseid' => $this->get_courseid()));
1044         foreach ($rs as $record) {
1045             $settings[$record->name] = $record;
1046         }
1047         $rs->close();
1048         if (!isset($settings['minmaxtouse'])) {
1049             $settings['minmaxtouse'] = (object) array('name' => 'minmaxtouse', 'value' => $CFG->grade_minmaxtouse);
1050         }
1051         $grade_setting->set_source_array($settings);
1054         // Annotations (both as final as far as they are going to be exported in next steps)
1055         $grade_item->annotate_ids('scalefinal', 'scaleid'); // Straight as scalefinal because it's > 0
1056         $grade_item->annotate_ids('outcomefinal', 'outcomeid');
1058         //just in case there are any users not already annotated by the activities
1059         $grade_grade->annotate_ids('userfinal', 'userid');
1061         // Return the root element
1062         return $gradebook;
1063     }
1066 /**
1067  * Step in charge of constructing the grade_history.xml file containing the grade histories.
1068  */
1069 class backup_grade_history_structure_step extends backup_structure_step {
1071     /**
1072      * Limit the execution.
1073      *
1074      * This applies the same logic than the one applied to {@link backup_gradebook_structure_step},
1075      * because we do not want to save the history of items which are not backed up. At least for now.
1076      */
1077     protected function execute_condition() {
1078         $courseid = $this->get_courseid();
1079         if ($courseid == SITEID) {
1080             return false;
1081         }
1083         return backup_plan_dbops::require_gradebook_backup($courseid, $this->get_backupid());
1084     }
1086     protected function define_structure() {
1088         // Settings to use.
1089         $userinfo = $this->get_setting_value('users');
1090         $history = $this->get_setting_value('grade_histories');
1092         // Create the nested elements.
1093         $bookhistory = new backup_nested_element('grade_history');
1094         $grades = new backup_nested_element('grade_grades');
1095         $grade = new backup_nested_element('grade_grade', array('id'), array(
1096             'action', 'oldid', 'source', 'loggeduser', 'itemid', 'userid',
1097             'rawgrade', 'rawgrademax', 'rawgrademin', 'rawscaleid',
1098             'usermodified', 'finalgrade', 'hidden', 'locked', 'locktime', 'exported', 'overridden',
1099             'excluded', 'feedback', 'feedbackformat', 'information',
1100             'informationformat', 'timemodified'));
1102         // Build the tree.
1103         $bookhistory->add_child($grades);
1104         $grades->add_child($grade);
1106         // This only happens if we are including user info and history.
1107         if ($userinfo && $history) {
1108             // Only keep the history of grades related to items which have been backed up, The query is
1109             // similar (but not identical) to the one used in backup_gradebook_structure_step::define_structure().
1110             $gradesql = "SELECT ggh.*
1111                            FROM {grade_grades_history} ggh
1112                            JOIN {grade_items} gi ON ggh.itemid = gi.id
1113                           WHERE gi.courseid = :courseid
1114                             AND (gi.itemtype = 'manual' OR gi.itemtype = 'course' OR gi.itemtype = 'category')";
1115             $grade->set_source_sql($gradesql, array('courseid' => backup::VAR_COURSEID));
1116         }
1118         // Annotations. (Final annotations as this step is part of the final task).
1119         $grade->annotate_ids('scalefinal', 'rawscaleid');
1120         $grade->annotate_ids('userfinal', 'loggeduser');
1121         $grade->annotate_ids('userfinal', 'userid');
1122         $grade->annotate_ids('userfinal', 'usermodified');
1124         // Return the root element.
1125         return $bookhistory;
1126     }
1130 /**
1131  * structure step in charge if constructing the completion.xml file for all the users completion
1132  * information in a given activity
1133  */
1134 class backup_userscompletion_structure_step extends backup_structure_step {
1136     /**
1137      * Skip completion on the front page.
1138      * @return bool
1139      */
1140     protected function execute_condition() {
1141         return ($this->get_courseid() != SITEID);
1142     }
1144     protected function define_structure() {
1146         // Define each element separated
1148         $completions = new backup_nested_element('completions');
1150         $completion = new backup_nested_element('completion', array('id'), array(
1151             'userid', 'completionstate', 'viewed', 'timemodified'));
1153         // Build the tree
1155         $completions->add_child($completion);
1157         // Define sources
1159         $completion->set_source_table('course_modules_completion', array('coursemoduleid' => backup::VAR_MODID));
1161         // Define id annotations
1163         $completion->annotate_ids('user', 'userid');
1165         // Return the root element (completions)
1166         return $completions;
1167     }
1170 /**
1171  * structure step in charge of constructing the main groups.xml file for all the groups and
1172  * groupings information already annotated
1173  */
1174 class backup_groups_structure_step extends backup_structure_step {
1176     protected function define_structure() {
1178         // To know if we are including users.
1179         $userinfo = $this->get_setting_value('users');
1180         // To know if we are including groups and groupings.
1181         $groupinfo = $this->get_setting_value('groups');
1183         // Define each element separated
1185         $groups = new backup_nested_element('groups');
1187         $group = new backup_nested_element('group', array('id'), array(
1188             'name', 'idnumber', 'description', 'descriptionformat', 'enrolmentkey',
1189             'picture', 'hidepicture', 'timecreated', 'timemodified'));
1191         $members = new backup_nested_element('group_members');
1193         $member = new backup_nested_element('group_member', array('id'), array(
1194             'userid', 'timeadded', 'component', 'itemid'));
1196         $groupings = new backup_nested_element('groupings');
1198         $grouping = new backup_nested_element('grouping', 'id', array(
1199             'name', 'idnumber', 'description', 'descriptionformat', 'configdata',
1200             'timecreated', 'timemodified'));
1202         $groupinggroups = new backup_nested_element('grouping_groups');
1204         $groupinggroup = new backup_nested_element('grouping_group', array('id'), array(
1205             'groupid', 'timeadded'));
1207         // Build the tree
1209         $groups->add_child($group);
1210         $groups->add_child($groupings);
1212         $group->add_child($members);
1213         $members->add_child($member);
1215         $groupings->add_child($grouping);
1216         $grouping->add_child($groupinggroups);
1217         $groupinggroups->add_child($groupinggroup);
1219         // Define sources
1221         // This only happens if we are including groups/groupings.
1222         if ($groupinfo) {
1223             $group->set_source_sql("
1224                 SELECT g.*
1225                   FROM {groups} g
1226                   JOIN {backup_ids_temp} bi ON g.id = bi.itemid
1227                  WHERE bi.backupid = ?
1228                    AND bi.itemname = 'groupfinal'", array(backup::VAR_BACKUPID));
1230             $grouping->set_source_sql("
1231                 SELECT g.*
1232                   FROM {groupings} g
1233                   JOIN {backup_ids_temp} bi ON g.id = bi.itemid
1234                  WHERE bi.backupid = ?
1235                    AND bi.itemname = 'groupingfinal'", array(backup::VAR_BACKUPID));
1236             $groupinggroup->set_source_table('groupings_groups', array('groupingid' => backup::VAR_PARENTID));
1238             // This only happens if we are including users.
1239             if ($userinfo) {
1240                 $member->set_source_table('groups_members', array('groupid' => backup::VAR_PARENTID));
1241             }
1242         }
1244         // Define id annotations (as final)
1246         $member->annotate_ids('userfinal', 'userid');
1248         // Define file annotations
1250         $group->annotate_files('group', 'description', 'id');
1251         $group->annotate_files('group', 'icon', 'id');
1252         $grouping->annotate_files('grouping', 'description', 'id');
1254         // Return the root element (groups)
1255         return $groups;
1256     }
1259 /**
1260  * structure step in charge of constructing the main users.xml file for all the users already
1261  * annotated (final). Includes custom profile fields, preferences, tags, role assignments and
1262  * overrides.
1263  */
1264 class backup_users_structure_step extends backup_structure_step {
1266     protected function define_structure() {
1267         global $CFG;
1269         // To know if we are anonymizing users
1270         $anonymize = $this->get_setting_value('anonymize');
1271         // To know if we are including role assignments
1272         $roleassignments = $this->get_setting_value('role_assignments');
1274         // Define each element separate.
1276         $users = new backup_nested_element('users');
1278         // Create the array of user fields by hand, as far as we have various bits to control
1279         // anonymize option, password backup, mnethostid...
1281         // First, the fields not needing anonymization nor special handling
1282         $normalfields = array(
1283             'confirmed', 'policyagreed', 'deleted',
1284             'lang', 'theme', 'timezone', 'firstaccess',
1285             'lastaccess', 'lastlogin', 'currentlogin',
1286             'mailformat', 'maildigest', 'maildisplay',
1287             'autosubscribe', 'trackforums', 'timecreated',
1288             'timemodified', 'trustbitmask');
1290         // Then, the fields potentially needing anonymization
1291         $anonfields = array(
1292             'username', 'idnumber', 'email', 'icq', 'skype',
1293             'yahoo', 'aim', 'msn', 'phone1',
1294             'phone2', 'institution', 'department', 'address',
1295             'city', 'country', 'lastip', 'picture',
1296             'url', 'description', 'descriptionformat', 'imagealt', 'auth');
1297         $anonfields = array_merge($anonfields, get_all_user_name_fields());
1299         // Add anonymized fields to $userfields with custom final element
1300         foreach ($anonfields as $field) {
1301             if ($anonymize) {
1302                 $userfields[] = new anonymizer_final_element($field);
1303             } else {
1304                 $userfields[] = $field; // No anonymization, normally added
1305             }
1306         }
1308         // mnethosturl requires special handling (custom final element)
1309         $userfields[] = new mnethosturl_final_element('mnethosturl');
1311         // password added conditionally
1312         if (!empty($CFG->includeuserpasswordsinbackup)) {
1313             $userfields[] = 'password';
1314         }
1316         // Merge all the fields
1317         $userfields = array_merge($userfields, $normalfields);
1319         $user = new backup_nested_element('user', array('id', 'contextid'), $userfields);
1321         $customfields = new backup_nested_element('custom_fields');
1323         $customfield = new backup_nested_element('custom_field', array('id'), array(
1324             'field_name', 'field_type', 'field_data'));
1326         $tags = new backup_nested_element('tags');
1328         $tag = new backup_nested_element('tag', array('id'), array(
1329             'name', 'rawname'));
1331         $preferences = new backup_nested_element('preferences');
1333         $preference = new backup_nested_element('preference', array('id'), array(
1334             'name', 'value'));
1336         $roles = new backup_nested_element('roles');
1338         $overrides = new backup_nested_element('role_overrides');
1340         $override = new backup_nested_element('override', array('id'), array(
1341             'roleid', 'capability', 'permission', 'timemodified',
1342             'modifierid'));
1344         $assignments = new backup_nested_element('role_assignments');
1346         $assignment = new backup_nested_element('assignment', array('id'), array(
1347             'roleid', 'userid', 'timemodified', 'modifierid', 'component', //TODO: MDL-22793 add itemid here
1348             'sortorder'));
1350         // Build the tree
1352         $users->add_child($user);
1354         $user->add_child($customfields);
1355         $customfields->add_child($customfield);
1357         $user->add_child($tags);
1358         $tags->add_child($tag);
1360         $user->add_child($preferences);
1361         $preferences->add_child($preference);
1363         $user->add_child($roles);
1365         $roles->add_child($overrides);
1366         $roles->add_child($assignments);
1368         $overrides->add_child($override);
1369         $assignments->add_child($assignment);
1371         // Define sources
1373         $user->set_source_sql('SELECT u.*, c.id AS contextid, m.wwwroot AS mnethosturl
1374                                  FROM {user} u
1375                                  JOIN {backup_ids_temp} bi ON bi.itemid = u.id
1376                             LEFT JOIN {context} c ON c.instanceid = u.id AND c.contextlevel = ' . CONTEXT_USER . '
1377                             LEFT JOIN {mnet_host} m ON m.id = u.mnethostid
1378                                 WHERE bi.backupid = ?
1379                                   AND bi.itemname = ?', array(
1380                                       backup_helper::is_sqlparam($this->get_backupid()),
1381                                       backup_helper::is_sqlparam('userfinal')));
1383         // All the rest on information is only added if we arent
1384         // in an anonymized backup
1385         if (!$anonymize) {
1386             $customfield->set_source_sql('SELECT f.id, f.shortname, f.datatype, d.data
1387                                             FROM {user_info_field} f
1388                                             JOIN {user_info_data} d ON d.fieldid = f.id
1389                                            WHERE d.userid = ?', array(backup::VAR_PARENTID));
1391             $customfield->set_source_alias('shortname', 'field_name');
1392             $customfield->set_source_alias('datatype',  'field_type');
1393             $customfield->set_source_alias('data',      'field_data');
1395             $tag->set_source_sql('SELECT t.id, t.name, t.rawname
1396                                     FROM {tag} t
1397                                     JOIN {tag_instance} ti ON ti.tagid = t.id
1398                                    WHERE ti.itemtype = ?
1399                                      AND ti.itemid = ?', array(
1400                                          backup_helper::is_sqlparam('user'),
1401                                          backup::VAR_PARENTID));
1403             $preference->set_source_table('user_preferences', array('userid' => backup::VAR_PARENTID));
1405             $override->set_source_table('role_capabilities', array('contextid' => '/users/user/contextid'));
1407             // Assignments only added if specified
1408             if ($roleassignments) {
1409                 $assignment->set_source_table('role_assignments', array('contextid' => '/users/user/contextid'));
1410             }
1412             // Define id annotations (as final)
1413             $override->annotate_ids('rolefinal', 'roleid');
1414         }
1416         // Return root element (users)
1417         return $users;
1418     }
1421 /**
1422  * structure step in charge of constructing the block.xml file for one
1423  * given block (instance and positions). If the block has custom DB structure
1424  * that will go to a separate file (different step defined in block class)
1425  */
1426 class backup_block_instance_structure_step extends backup_structure_step {
1428     protected function define_structure() {
1429         global $DB;
1431         // Define each element separated
1433         $block = new backup_nested_element('block', array('id', 'contextid', 'version'), array(
1434                 'blockname', 'parentcontextid', 'showinsubcontexts', 'pagetypepattern',
1435                 'subpagepattern', 'defaultregion', 'defaultweight', 'configdata',
1436                 'timecreated', 'timemodified'));
1438         $positions = new backup_nested_element('block_positions');
1440         $position = new backup_nested_element('block_position', array('id'), array(
1441             'contextid', 'pagetype', 'subpage', 'visible',
1442             'region', 'weight'));
1444         // Build the tree
1446         $block->add_child($positions);
1447         $positions->add_child($position);
1449         // Transform configdata information if needed (process links and friends)
1450         $blockrec = $DB->get_record('block_instances', array('id' => $this->task->get_blockid()));
1451         if ($attrstotransform = $this->task->get_configdata_encoded_attributes()) {
1452             $configdata = (array)unserialize(base64_decode($blockrec->configdata));
1453             foreach ($configdata as $attribute => $value) {
1454                 if (in_array($attribute, $attrstotransform)) {
1455                     $configdata[$attribute] = $this->contenttransformer->process($value);
1456                 }
1457             }
1458             $blockrec->configdata = base64_encode(serialize((object)$configdata));
1459         }
1460         $blockrec->contextid = $this->task->get_contextid();
1461         // Get the version of the block
1462         $blockrec->version = get_config('block_'.$this->task->get_blockname(), 'version');
1464         // Define sources
1466         $block->set_source_array(array($blockrec));
1468         $position->set_source_table('block_positions', array('blockinstanceid' => backup::VAR_PARENTID));
1470         // File anotations (for fileareas specified on each block)
1471         foreach ($this->task->get_fileareas() as $filearea) {
1472             $block->annotate_files('block_' . $this->task->get_blockname(), $filearea, null);
1473         }
1475         // Return the root element (block)
1476         return $block;
1477     }
1480 /**
1481  * structure step in charge of constructing the logs.xml file for all the log records found
1482  * in course. Note that we are sending to backup ALL the log records having cmid = 0. That
1483  * includes some records that won't be restoreable (like 'upload', 'calendar'...) but we do
1484  * that just in case they become restored some day in the future
1485  */
1486 class backup_course_logs_structure_step extends backup_structure_step {
1488     protected function define_structure() {
1490         // Define each element separated
1492         $logs = new backup_nested_element('logs');
1494         $log = new backup_nested_element('log', array('id'), array(
1495             'time', 'userid', 'ip', 'module',
1496             'action', 'url', 'info'));
1498         // Build the tree
1500         $logs->add_child($log);
1502         // Define sources (all the records belonging to the course, having cmid = 0)
1504         $log->set_source_table('log', array('course' => backup::VAR_COURSEID, 'cmid' => backup_helper::is_sqlparam(0)));
1506         // Annotations
1507         // NOTE: We don't annotate users from logs as far as they MUST be
1508         //       always annotated by the course (enrol, ras... whatever)
1510         // Return the root element (logs)
1512         return $logs;
1513     }
1516 /**
1517  * structure step in charge of constructing the logs.xml file for all the log records found
1518  * in activity
1519  */
1520 class backup_activity_logs_structure_step extends backup_structure_step {
1522     protected function define_structure() {
1524         // Define each element separated
1526         $logs = new backup_nested_element('logs');
1528         $log = new backup_nested_element('log', array('id'), array(
1529             'time', 'userid', 'ip', 'module',
1530             'action', 'url', 'info'));
1532         // Build the tree
1534         $logs->add_child($log);
1536         // Define sources
1538         $log->set_source_table('log', array('cmid' => backup::VAR_MODID));
1540         // Annotations
1541         // NOTE: We don't annotate users from logs as far as they MUST be
1542         //       always annotated by the activity (true participants).
1544         // Return the root element (logs)
1546         return $logs;
1547     }
1550 /**
1551  * Structure step in charge of constructing the logstores.xml file for the course logs.
1552  *
1553  * This backup step will backup the logs for all the enabled logstore subplugins supporting
1554  * it, for logs belonging to the course level.
1555  */
1556 class backup_course_logstores_structure_step extends backup_structure_step {
1558     protected function define_structure() {
1560         // Define the structure of logstores container.
1561         $logstores = new backup_nested_element('logstores');
1562         $logstore = new backup_nested_element('logstore');
1563         $logstores->add_child($logstore);
1565         // Add the tool_log logstore subplugins information to the logstore element.
1566         $this->add_subplugin_structure('logstore', $logstore, true, 'tool', 'log');
1568         return $logstores;
1569     }
1572 /**
1573  * Structure step in charge of constructing the logstores.xml file for the activity logs.
1574  *
1575  * Note: Activity structure is completely equivalent to the course one, so just extend it.
1576  */
1577 class backup_activity_logstores_structure_step extends backup_course_logstores_structure_step {
1580 /**
1581  * Course competencies backup structure step.
1582  */
1583 class backup_course_competencies_structure_step extends backup_structure_step {
1585     protected function define_structure() {
1586         $userinfo = $this->get_setting_value('users');
1588         $wrapper = new backup_nested_element('course_competencies');
1590         $settings = new backup_nested_element('settings', array('id'), array('pushratingstouserplans'));
1591         $wrapper->add_child($settings);
1593         $sql = 'SELECT s.pushratingstouserplans
1594                   FROM {' . \core_competency\course_competency_settings::TABLE . '} s
1595                  WHERE s.courseid = :courseid';
1596         $settings->set_source_sql($sql, array('courseid' => backup::VAR_COURSEID));
1598         $competencies = new backup_nested_element('competencies');
1599         $wrapper->add_child($competencies);
1601         $competency = new backup_nested_element('competency', null, array('id', 'idnumber', 'ruleoutcome',
1602             'sortorder', 'frameworkid', 'frameworkidnumber'));
1603         $competencies->add_child($competency);
1605         $sql = 'SELECT c.id, c.idnumber, cc.ruleoutcome, cc.sortorder, f.id AS frameworkid, f.idnumber AS frameworkidnumber
1606                   FROM {' . \core_competency\course_competency::TABLE . '} cc
1607                   JOIN {' . \core_competency\competency::TABLE . '} c ON c.id = cc.competencyid
1608                   JOIN {' . \core_competency\competency_framework::TABLE . '} f ON f.id = c.competencyframeworkid
1609                  WHERE cc.courseid = :courseid
1610               ORDER BY cc.sortorder';
1611         $competency->set_source_sql($sql, array('courseid' => backup::VAR_COURSEID));
1613         $usercomps = new backup_nested_element('user_competencies');
1614         $wrapper->add_child($usercomps);
1615         if ($userinfo) {
1616             $usercomp = new backup_nested_element('user_competency', null, array('userid', 'competencyid',
1617                 'proficiency', 'grade'));
1618             $usercomps->add_child($usercomp);
1620             $sql = 'SELECT ucc.userid, ucc.competencyid, ucc.proficiency, ucc.grade
1621                       FROM {' . \core_competency\user_competency_course::TABLE . '} ucc
1622                      WHERE ucc.courseid = :courseid
1623                        AND ucc.grade IS NOT NULL';
1624             $usercomp->set_source_sql($sql, array('courseid' => backup::VAR_COURSEID));
1625             $usercomp->annotate_ids('user', 'userid');
1626         }
1628         return $wrapper;
1629     }
1631     /**
1632      * Execute conditions.
1633      *
1634      * @return bool
1635      */
1636     protected function execute_condition() {
1638         // Do not execute if competencies are not included.
1639         if (!$this->get_setting_value('competencies')) {
1640             return false;
1641         }
1643         return true;
1644     }
1647 /**
1648  * Activity competencies backup structure step.
1649  */
1650 class backup_activity_competencies_structure_step extends backup_structure_step {
1652     protected function define_structure() {
1653         $wrapper = new backup_nested_element('course_module_competencies');
1655         $competencies = new backup_nested_element('competencies');
1656         $wrapper->add_child($competencies);
1658         $competency = new backup_nested_element('competency', null, array('idnumber', 'ruleoutcome',
1659             'sortorder', 'frameworkidnumber'));
1660         $competencies->add_child($competency);
1662         $sql = 'SELECT c.idnumber, cmc.ruleoutcome, cmc.sortorder, f.idnumber AS frameworkidnumber
1663                   FROM {' . \core_competency\course_module_competency::TABLE . '} cmc
1664                   JOIN {' . \core_competency\competency::TABLE . '} c ON c.id = cmc.competencyid
1665                   JOIN {' . \core_competency\competency_framework::TABLE . '} f ON f.id = c.competencyframeworkid
1666                  WHERE cmc.cmid = :coursemoduleid
1667               ORDER BY cmc.sortorder';
1668         $competency->set_source_sql($sql, array('coursemoduleid' => backup::VAR_MODID));
1670         return $wrapper;
1671     }
1673     /**
1674      * Execute conditions.
1675      *
1676      * @return bool
1677      */
1678     protected function execute_condition() {
1680         // Do not execute if competencies are not included.
1681         if (!$this->get_setting_value('competencies')) {
1682             return false;
1683         }
1685         return true;
1686     }
1689 /**
1690  * structure in charge of constructing the inforef.xml file for all the items we want
1691  * to have referenced there (users, roles, files...)
1692  */
1693 class backup_inforef_structure_step extends backup_structure_step {
1695     protected function define_structure() {
1697         // Items we want to include in the inforef file.
1698         $items = backup_helper::get_inforef_itemnames();
1700         // Build the tree
1702         $inforef = new backup_nested_element('inforef');
1704         // For each item, conditionally, if there are already records, build element
1705         foreach ($items as $itemname) {
1706             if (backup_structure_dbops::annotations_exist($this->get_backupid(), $itemname)) {
1707                 $elementroot = new backup_nested_element($itemname . 'ref');
1708                 $element = new backup_nested_element($itemname, array(), array('id'));
1709                 $inforef->add_child($elementroot);
1710                 $elementroot->add_child($element);
1711                 $element->set_source_sql("
1712                     SELECT itemid AS id
1713                      FROM {backup_ids_temp}
1714                     WHERE backupid = ?
1715                       AND itemname = ?",
1716                    array(backup::VAR_BACKUPID, backup_helper::is_sqlparam($itemname)));
1717             }
1718         }
1720         // We don't annotate anything there, but rely in the next step
1721         // (move_inforef_annotations_to_final) that will change all the
1722         // already saved 'inforref' entries to their 'final' annotations.
1723         return $inforef;
1724     }
1727 /**
1728  * This step will get all the annotations already processed to inforef.xml file and
1729  * transform them into 'final' annotations.
1730  */
1731 class move_inforef_annotations_to_final extends backup_execution_step {
1733     protected function define_execution() {
1735         // Items we want to include in the inforef file
1736         $items = backup_helper::get_inforef_itemnames();
1737         $progress = $this->task->get_progress();
1738         $progress->start_progress($this->get_name(), count($items));
1739         $done = 1;
1740         foreach ($items as $itemname) {
1741             // Delegate to dbops
1742             backup_structure_dbops::move_annotations_to_final($this->get_backupid(),
1743                     $itemname, $progress);
1744             $progress->progress($done++);
1745         }
1746         $progress->end_progress();
1747     }
1750 /**
1751  * structure in charge of constructing the files.xml file with all the
1752  * annotated (final) files along the process. At, the same time, and
1753  * using one specialised nested_element, will copy them form moodle storage
1754  * to backup storage
1755  */
1756 class backup_final_files_structure_step extends backup_structure_step {
1758     protected function define_structure() {
1760         // Define elements
1762         $files = new backup_nested_element('files');
1764         $file = new file_nested_element('file', array('id'), array(
1765             'contenthash', 'contextid', 'component', 'filearea', 'itemid',
1766             'filepath', 'filename', 'userid', 'filesize',
1767             'mimetype', 'status', 'timecreated', 'timemodified',
1768             'source', 'author', 'license', 'sortorder',
1769             'repositorytype', 'repositoryid', 'reference'));
1771         // Build the tree
1773         $files->add_child($file);
1775         // Define sources
1777         $file->set_source_sql("SELECT f.*, r.type AS repositorytype, fr.repositoryid, fr.reference
1778                                  FROM {files} f
1779                                       LEFT JOIN {files_reference} fr ON fr.id = f.referencefileid
1780                                       LEFT JOIN {repository_instances} ri ON ri.id = fr.repositoryid
1781                                       LEFT JOIN {repository} r ON r.id = ri.typeid
1782                                       JOIN {backup_ids_temp} bi ON f.id = bi.itemid
1783                                 WHERE bi.backupid = ?
1784                                   AND bi.itemname = 'filefinal'", array(backup::VAR_BACKUPID));
1786         return $files;
1787     }
1790 /**
1791  * Structure step in charge of creating the main moodle_backup.xml file
1792  * where all the information related to the backup, settings, license and
1793  * other information needed on restore is added*/
1794 class backup_main_structure_step extends backup_structure_step {
1796     protected function define_structure() {
1798         global $CFG;
1800         $info = array();
1802         $info['name'] = $this->get_setting_value('filename');
1803         $info['moodle_version'] = $CFG->version;
1804         $info['moodle_release'] = $CFG->release;
1805         $info['backup_version'] = $CFG->backup_version;
1806         $info['backup_release'] = $CFG->backup_release;
1807         $info['backup_date']    = time();
1808         $info['backup_uniqueid']= $this->get_backupid();
1809         $info['mnet_remoteusers']=backup_controller_dbops::backup_includes_mnet_remote_users($this->get_backupid());
1810         $info['include_files'] = backup_controller_dbops::backup_includes_files($this->get_backupid());
1811         $info['include_file_references_to_external_content'] =
1812                 backup_controller_dbops::backup_includes_file_references($this->get_backupid());
1813         $info['original_wwwroot']=$CFG->wwwroot;
1814         $info['original_site_identifier_hash'] = md5(get_site_identifier());
1815         $info['original_course_id'] = $this->get_courseid();
1816         $originalcourseinfo = backup_controller_dbops::backup_get_original_course_info($this->get_courseid());
1817         $info['original_course_format'] = $originalcourseinfo->format;
1818         $info['original_course_fullname']  = $originalcourseinfo->fullname;
1819         $info['original_course_shortname'] = $originalcourseinfo->shortname;
1820         $info['original_course_startdate'] = $originalcourseinfo->startdate;
1821         $info['original_course_enddate']   = $originalcourseinfo->enddate;
1822         $info['original_course_contextid'] = context_course::instance($this->get_courseid())->id;
1823         $info['original_system_contextid'] = context_system::instance()->id;
1825         // Get more information from controller
1826         list($dinfo, $cinfo, $sinfo) = backup_controller_dbops::get_moodle_backup_information(
1827                 $this->get_backupid(), $this->get_task()->get_progress());
1829         // Define elements
1831         $moodle_backup = new backup_nested_element('moodle_backup');
1833         $information = new backup_nested_element('information', null, array(
1834             'name', 'moodle_version', 'moodle_release', 'backup_version',
1835             'backup_release', 'backup_date', 'mnet_remoteusers', 'include_files', 'include_file_references_to_external_content', 'original_wwwroot',
1836             'original_site_identifier_hash', 'original_course_id', 'original_course_format',
1837             'original_course_fullname', 'original_course_shortname', 'original_course_startdate', 'original_course_enddate',
1838             'original_course_contextid', 'original_system_contextid'));
1840         $details = new backup_nested_element('details');
1842         $detail = new backup_nested_element('detail', array('backup_id'), array(
1843             'type', 'format', 'interactive', 'mode',
1844             'execution', 'executiontime'));
1846         $contents = new backup_nested_element('contents');
1848         $activities = new backup_nested_element('activities');
1850         $activity = new backup_nested_element('activity', null, array(
1851             'moduleid', 'sectionid', 'modulename', 'title',
1852             'directory'));
1854         $sections = new backup_nested_element('sections');
1856         $section = new backup_nested_element('section', null, array(
1857             'sectionid', 'title', 'directory'));
1859         $course = new backup_nested_element('course', null, array(
1860             'courseid', 'title', 'directory'));
1862         $settings = new backup_nested_element('settings');
1864         $setting = new backup_nested_element('setting', null, array(
1865             'level', 'section', 'activity', 'name', 'value'));
1867         // Build the tree
1869         $moodle_backup->add_child($information);
1871         $information->add_child($details);
1872         $details->add_child($detail);
1874         $information->add_child($contents);
1875         if (!empty($cinfo['activities'])) {
1876             $contents->add_child($activities);
1877             $activities->add_child($activity);
1878         }
1879         if (!empty($cinfo['sections'])) {
1880             $contents->add_child($sections);
1881             $sections->add_child($section);
1882         }
1883         if (!empty($cinfo['course'])) {
1884             $contents->add_child($course);
1885         }
1887         $information->add_child($settings);
1888         $settings->add_child($setting);
1891         // Set the sources
1893         $information->set_source_array(array((object)$info));
1895         $detail->set_source_array($dinfo);
1897         $activity->set_source_array($cinfo['activities']);
1899         $section->set_source_array($cinfo['sections']);
1901         $course->set_source_array($cinfo['course']);
1903         $setting->set_source_array($sinfo);
1905         // Prepare some information to be sent to main moodle_backup.xml file
1906         return $moodle_backup;
1907     }
1911 /**
1912  * Execution step that will generate the final zip (.mbz) file with all the contents
1913  */
1914 class backup_zip_contents extends backup_execution_step implements file_progress {
1915     /**
1916      * @var bool True if we have started tracking progress
1917      */
1918     protected $startedprogress;
1920     protected function define_execution() {
1922         // Get basepath
1923         $basepath = $this->get_basepath();
1925         // Get the list of files in directory
1926         $filestemp = get_directory_list($basepath, '', false, true, true);
1927         $files = array();
1928         foreach ($filestemp as $file) { // Add zip paths and fs paths to all them
1929             $files[$file] = $basepath . '/' . $file;
1930         }
1932         // Add the log file if exists
1933         $logfilepath = $basepath . '.log';
1934         if (file_exists($logfilepath)) {
1935              $files['moodle_backup.log'] = $logfilepath;
1936         }
1938         // Calculate the zip fullpath (in OS temp area it's always backup.mbz)
1939         $zipfile = $basepath . '/backup.mbz';
1941         // Get the zip packer
1942         $zippacker = get_file_packer('application/vnd.moodle.backup');
1944         // Track overall progress for the 2 long-running steps (archive to
1945         // pathname, get backup information).
1946         $reporter = $this->task->get_progress();
1947         $reporter->start_progress('backup_zip_contents', 2);
1949         // Zip files
1950         $result = $zippacker->archive_to_pathname($files, $zipfile, true, $this);
1952         // If any sub-progress happened, end it.
1953         if ($this->startedprogress) {
1954             $this->task->get_progress()->end_progress();
1955             $this->startedprogress = false;
1956         } else {
1957             // No progress was reported, manually move it on to the next overall task.
1958             $reporter->progress(1);
1959         }
1961         // Something went wrong.
1962         if ($result === false) {
1963             @unlink($zipfile);
1964             throw new backup_step_exception('error_zip_packing', '', 'An error was encountered while trying to generate backup zip');
1965         }
1966         // Read to make sure it is a valid backup. Refer MDL-37877 . Delete it, if found not to be valid.
1967         try {
1968             backup_general_helper::get_backup_information_from_mbz($zipfile, $this);
1969         } catch (backup_helper_exception $e) {
1970             @unlink($zipfile);
1971             throw new backup_step_exception('error_zip_packing', '', $e->debuginfo);
1972         }
1974         // If any sub-progress happened, end it.
1975         if ($this->startedprogress) {
1976             $this->task->get_progress()->end_progress();
1977             $this->startedprogress = false;
1978         } else {
1979             $reporter->progress(2);
1980         }
1981         $reporter->end_progress();
1982     }
1984     /**
1985      * Implementation for file_progress interface to display unzip progress.
1986      *
1987      * @param int $progress Current progress
1988      * @param int $max Max value
1989      */
1990     public function progress($progress = file_progress::INDETERMINATE, $max = file_progress::INDETERMINATE) {
1991         $reporter = $this->task->get_progress();
1993         // Start tracking progress if necessary.
1994         if (!$this->startedprogress) {
1995             $reporter->start_progress('extract_file_to_dir', ($max == file_progress::INDETERMINATE)
1996                     ? \core\progress\base::INDETERMINATE : $max);
1997             $this->startedprogress = true;
1998         }
2000         // Pass progress through to whatever handles it.
2001         $reporter->progress(($progress == file_progress::INDETERMINATE)
2002                 ? \core\progress\base::INDETERMINATE : $progress);
2003      }
2006 /**
2007  * This step will send the generated backup file to its final destination
2008  */
2009 class backup_store_backup_file extends backup_execution_step {
2011     protected function define_execution() {
2013         // Get basepath
2014         $basepath = $this->get_basepath();
2016         // Calculate the zip fullpath (in OS temp area it's always backup.mbz)
2017         $zipfile = $basepath . '/backup.mbz';
2019         $has_file_references = backup_controller_dbops::backup_includes_file_references($this->get_backupid());
2020         // Perform storage and return it (TODO: shouldn't be array but proper result object)
2021         return array(
2022             'backup_destination' => backup_helper::store_backup_file($this->get_backupid(), $zipfile,
2023                     $this->task->get_progress()),
2024             'include_file_references_to_external_content' => $has_file_references
2025         );
2026     }
2030 /**
2031  * This step will search for all the activity (not calculations, categories nor aggregations) grade items
2032  * and put them to the backup_ids tables, to be used later as base to backup them
2033  */
2034 class backup_activity_grade_items_to_ids extends backup_execution_step {
2036     protected function define_execution() {
2038         // Fetch all activity grade items
2039         if ($items = grade_item::fetch_all(array(
2040                          'itemtype' => 'mod', 'itemmodule' => $this->task->get_modulename(),
2041                          'iteminstance' => $this->task->get_activityid(), 'courseid' => $this->task->get_courseid()))) {
2042             // Annotate them in backup_ids
2043             foreach ($items as $item) {
2044                 backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), 'grade_item', $item->id);
2045             }
2046         }
2047     }
2051 /**
2052  * This step allows enrol plugins to annotate custom fields.
2053  *
2054  * @package   core_backup
2055  * @copyright 2014 University of Wisconsin
2056  * @author    Matt Petro
2057  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2058  */
2059 class backup_enrolments_execution_step extends backup_execution_step {
2061     /**
2062      * Function that will contain all the code to be executed.
2063      */
2064     protected function define_execution() {
2065         global $DB;
2067         $plugins = enrol_get_plugins(true);
2068         $enrols = $DB->get_records('enrol', array(
2069                 'courseid' => $this->task->get_courseid()));
2071         // Allow each enrol plugin to add annotations.
2072         foreach ($enrols as $enrol) {
2073             if (isset($plugins[$enrol->enrol])) {
2074                 $plugins[$enrol->enrol]->backup_annotate_custom_fields($this, $enrol);
2075             }
2076         }
2077     }
2079     /**
2080      * Annotate a single name/id pair.
2081      * This can be called from {@link enrol_plugin::backup_annotate_custom_fields()}.
2082      *
2083      * @param string $itemname
2084      * @param int $itemid
2085      */
2086     public function annotate_id($itemname, $itemid) {
2087         backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), $itemname, $itemid);
2088     }
2091 /**
2092  * This step will annotate all the groups and groupings belonging to the course
2093  */
2094 class backup_annotate_course_groups_and_groupings extends backup_execution_step {
2096     protected function define_execution() {
2097         global $DB;
2099         // Get all the course groups
2100         if ($groups = $DB->get_records('groups', array(
2101                 'courseid' => $this->task->get_courseid()))) {
2102             foreach ($groups as $group) {
2103                 backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), 'group', $group->id);
2104             }
2105         }
2107         // Get all the course groupings
2108         if ($groupings = $DB->get_records('groupings', array(
2109                 'courseid' => $this->task->get_courseid()))) {
2110             foreach ($groupings as $grouping) {
2111                 backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), 'grouping', $grouping->id);
2112             }
2113         }
2114     }
2117 /**
2118  * This step will annotate all the groups belonging to already annotated groupings
2119  */
2120 class backup_annotate_groups_from_groupings extends backup_execution_step {
2122     protected function define_execution() {
2123         global $DB;
2125         // Fetch all the annotated groupings
2126         if ($groupings = $DB->get_records('backup_ids_temp', array(
2127                 'backupid' => $this->get_backupid(), 'itemname' => 'grouping'))) {
2128             foreach ($groupings as $grouping) {
2129                 if ($groups = $DB->get_records('groupings_groups', array(
2130                         'groupingid' => $grouping->itemid))) {
2131                     foreach ($groups as $group) {
2132                         backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), 'group', $group->groupid);
2133                     }
2134                 }
2135             }
2136         }
2137     }
2140 /**
2141  * This step will annotate all the scales belonging to already annotated outcomes
2142  */
2143 class backup_annotate_scales_from_outcomes extends backup_execution_step {
2145     protected function define_execution() {
2146         global $DB;
2148         // Fetch all the annotated outcomes
2149         if ($outcomes = $DB->get_records('backup_ids_temp', array(
2150                 'backupid' => $this->get_backupid(), 'itemname' => 'outcome'))) {
2151             foreach ($outcomes as $outcome) {
2152                 if ($scale = $DB->get_record('grade_outcomes', array(
2153                         'id' => $outcome->itemid))) {
2154                     // Annotate as scalefinal because it's > 0
2155                     backup_structure_dbops::insert_backup_ids_record($this->get_backupid(), 'scalefinal', $scale->scaleid);
2156                 }
2157             }
2158         }
2159     }
2162 /**
2163  * This step will generate all the file annotations for the already
2164  * annotated (final) question_categories. It calculates the different
2165  * contexts that are being backup and, annotates all the files
2166  * on every context belonging to the "question" component. As far as
2167  * we are always including *complete* question banks it is safe and
2168  * optimal to do that in this (one pass) way
2169  */
2170 class backup_annotate_all_question_files extends backup_execution_step {
2172     protected function define_execution() {
2173         global $DB;
2175         // Get all the different contexts for the final question_categories
2176         // annotated along the whole backup
2177         $rs = $DB->get_recordset_sql("SELECT DISTINCT qc.contextid
2178                                         FROM {question_categories} qc
2179                                         JOIN {backup_ids_temp} bi ON bi.itemid = qc.id
2180                                        WHERE bi.backupid = ?
2181                                          AND bi.itemname = 'question_categoryfinal'", array($this->get_backupid()));
2182         // To know about qtype specific components/fileareas
2183         $components = backup_qtype_plugin::get_components_and_fileareas();
2184         // Let's loop
2185         foreach($rs as $record) {
2186             // Backup all the file areas the are managed by the core question component.
2187             // That is, by the question_type base class. In particular, we don't want
2188             // to include files belonging to responses here.
2189             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', 'questiontext', null);
2190             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', 'generalfeedback', null);
2191             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', 'answer', null);
2192             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', 'answerfeedback', null);
2193             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', 'hint', null);
2194             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', 'correctfeedback', null);
2195             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', 'partiallycorrectfeedback', null);
2196             backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, 'question', 'incorrectfeedback', null);
2198             // For files belonging to question types, we make the leap of faith that
2199             // all the files belonging to the question type are part of the question definition,
2200             // so we can just backup all the files in bulk, without specifying each
2201             // file area name separately.
2202             foreach ($components as $component => $fileareas) {
2203                 backup_structure_dbops::annotate_files($this->get_backupid(), $record->contextid, $component, null, null);
2204             }
2205         }
2206         $rs->close();
2207     }
2210 /**
2211  * structure step in charge of constructing the questions.xml file for all the
2212  * question categories and questions required by the backup
2213  * and letters related to one activity
2214  */
2215 class backup_questions_structure_step extends backup_structure_step {
2217     protected function define_structure() {
2219         // Define each element separated
2221         $qcategories = new backup_nested_element('question_categories');
2223         $qcategory = new backup_nested_element('question_category', array('id'), array(
2224             'name', 'contextid', 'contextlevel', 'contextinstanceid',
2225             'info', 'infoformat', 'stamp', 'parent',
2226             'sortorder', 'idnumber'));
2228         $questions = new backup_nested_element('questions');
2230         $question = new backup_nested_element('question', array('id'), array(
2231             'parent', 'name', 'questiontext', 'questiontextformat',
2232             'generalfeedback', 'generalfeedbackformat', 'defaultmark', 'penalty',
2233             'qtype', 'length', 'stamp', 'version',
2234             'hidden', 'timecreated', 'timemodified', 'createdby', 'modifiedby', 'idnumber'));
2236         // attach qtype plugin structure to $question element, only one allowed
2237         $this->add_plugin_structure('qtype', $question, false);
2239         // attach local plugin stucture to $question element, multiple allowed
2240         $this->add_plugin_structure('local', $question, true);
2242         $qhints = new backup_nested_element('question_hints');
2244         $qhint = new backup_nested_element('question_hint', array('id'), array(
2245             'hint', 'hintformat', 'shownumcorrect', 'clearwrong', 'options'));
2247         $tags = new backup_nested_element('tags');
2249         $tag = new backup_nested_element('tag', array('id', 'contextid'), array('name', 'rawname'));
2251         // Build the tree
2253         $qcategories->add_child($qcategory);
2254         $qcategory->add_child($questions);
2255         $questions->add_child($question);
2256         $question->add_child($qhints);
2257         $qhints->add_child($qhint);
2259         $question->add_child($tags);
2260         $tags->add_child($tag);
2262         // Define the sources
2264         $qcategory->set_source_sql("
2265             SELECT gc.*, contextlevel, instanceid AS contextinstanceid
2266               FROM {question_categories} gc
2267               JOIN {backup_ids_temp} bi ON bi.itemid = gc.id
2268               JOIN {context} co ON co.id = gc.contextid
2269              WHERE bi.backupid = ?
2270                AND bi.itemname = 'question_categoryfinal'", array(backup::VAR_BACKUPID));
2272         $question->set_source_table('question', array('category' => backup::VAR_PARENTID));
2274         $qhint->set_source_sql('
2275                 SELECT *
2276                 FROM {question_hints}
2277                 WHERE questionid = :questionid
2278                 ORDER BY id',
2279                 array('questionid' => backup::VAR_PARENTID));
2281         $tag->set_source_sql("SELECT t.id, ti.contextid, t.name, t.rawname
2282                               FROM {tag} t
2283                               JOIN {tag_instance} ti ON ti.tagid = t.id
2284                               WHERE ti.itemid = ?
2285                               AND ti.itemtype = 'question'", array(backup::VAR_PARENTID));
2287         // don't need to annotate ids nor files
2288         // (already done by {@link backup_annotate_all_question_files}
2290         return $qcategories;
2291     }
2296 /**
2297  * This step will generate all the file  annotations for the already
2298  * annotated (final) users. Need to do this here because each user
2299  * has its own context and structure tasks only are able to handle
2300  * one context. Also, this step will guarantee that every user has
2301  * its context created (req for other steps)
2302  */
2303 class backup_annotate_all_user_files extends backup_execution_step {
2305     protected function define_execution() {
2306         global $DB;
2308         // List of fileareas we are going to annotate
2309         $fileareas = array('profile', 'icon');
2311         // Fetch all annotated (final) users
2312         $rs = $DB->get_recordset('backup_ids_temp', array(
2313             'backupid' => $this->get_backupid(), 'itemname' => 'userfinal'));
2314         $progress = $this->task->get_progress();
2315         $progress->start_progress($this->get_name());
2316         foreach ($rs as $record) {
2317             $userid = $record->itemid;
2318             $userctx = context_user::instance($userid, IGNORE_MISSING);
2319             if (!$userctx) {
2320                 continue; // User has not context, sure it's a deleted user, so cannot have files
2321             }
2322             // Proceed with every user filearea
2323             foreach ($fileareas as $filearea) {
2324                 // We don't need to specify itemid ($userid - 5th param) as far as by
2325                 // context we can get all the associated files. See MDL-22092
2326                 backup_structure_dbops::annotate_files($this->get_backupid(), $userctx->id, 'user', $filearea, null);
2327                 $progress->progress();
2328             }
2329         }
2330         $progress->end_progress();
2331         $rs->close();
2332     }
2336 /**
2337  * Defines the backup step for advanced grading methods attached to the activity module
2338  */
2339 class backup_activity_grading_structure_step extends backup_structure_step {
2341     /**
2342      * Include the grading.xml only if the module supports advanced grading
2343      */
2344     protected function execute_condition() {
2346         // No grades on the front page.
2347         if ($this->get_courseid() == SITEID) {
2348             return false;
2349         }
2351         return plugin_supports('mod', $this->get_task()->get_modulename(), FEATURE_ADVANCED_GRADING, false);
2352     }
2354     /**
2355      * Declares the gradable areas structures and data sources
2356      */
2357     protected function define_structure() {
2359         // To know if we are including userinfo
2360         $userinfo = $this->get_setting_value('userinfo');
2362         // Define the elements
2364         $areas = new backup_nested_element('areas');
2366         $area = new backup_nested_element('area', array('id'), array(
2367             'areaname', 'activemethod'));
2369         $definitions = new backup_nested_element('definitions');
2371         $definition = new backup_nested_element('definition', array('id'), array(
2372             'method', 'name', 'description', 'descriptionformat', 'status',
2373             'timecreated', 'timemodified', 'options'));
2375         $instances = new backup_nested_element('instances');
2377         $instance = new backup_nested_element('instance', array('id'), array(
2378             'raterid', 'itemid', 'rawgrade', 'status', 'feedback',
2379             'feedbackformat', 'timemodified'));
2381         // Build the tree including the method specific structures
2382         // (beware - the order of how gradingform plugins structures are attached is important)
2383         $areas->add_child($area);
2384         // attach local plugin stucture to $area element, multiple allowed
2385         $this->add_plugin_structure('local', $area, true);
2386         $area->add_child($definitions);
2387         $definitions->add_child($definition);
2388         $this->add_plugin_structure('gradingform', $definition, true);
2389         // attach local plugin stucture to $definition element, multiple allowed
2390         $this->add_plugin_structure('local', $definition, true);
2391         $definition->add_child($instances);
2392         $instances->add_child($instance);
2393         $this->add_plugin_structure('gradingform', $instance, false);
2394         // attach local plugin stucture to $instance element, multiple allowed
2395         $this->add_plugin_structure('local', $instance, true);
2397         // Define data sources
2399         $area->set_source_table('grading_areas', array('contextid' => backup::VAR_CONTEXTID,
2400             'component' => array('sqlparam' => 'mod_'.$this->get_task()->get_modulename())));
2402         $definition->set_source_table('grading_definitions', array('areaid' => backup::VAR_PARENTID));
2404         if ($userinfo) {
2405             $instance->set_source_table('grading_instances', array('definitionid' => backup::VAR_PARENTID));
2406         }
2408         // Annotate references
2409         $definition->annotate_files('grading', 'description', 'id');
2410         $instance->annotate_ids('user', 'raterid');
2412         // Return the root element
2413         return $areas;
2414     }
2418 /**
2419  * structure step in charge of constructing the grades.xml file for all the grade items
2420  * and letters related to one activity
2421  */
2422 class backup_activity_grades_structure_step extends backup_structure_step {
2424     /**
2425      * No grades on the front page.
2426      * @return bool
2427      */
2428     protected function execute_condition() {
2429         return ($this->get_courseid() != SITEID);
2430     }
2432     protected function define_structure() {
2433         global $CFG;
2435         require_once($CFG->libdir . '/grade/constants.php');
2437         // To know if we are including userinfo
2438         $userinfo = $this->get_setting_value('userinfo');
2440         // Define each element separated
2442         $book = new backup_nested_element('activity_gradebook');
2444         $items = new backup_nested_element('grade_items');
2446         $item = new backup_nested_element('grade_item', array('id'), array(
2447             'categoryid', 'itemname', 'itemtype', 'itemmodule',
2448             'iteminstance', 'itemnumber', 'iteminfo', 'idnumber',
2449             'calculation', 'gradetype', 'grademax', 'grademin',
2450             'scaleid', 'outcomeid', 'gradepass', 'multfactor',
2451             'plusfactor', 'aggregationcoef', 'aggregationcoef2', 'weightoverride',
2452             'sortorder', 'display', 'decimals', 'hidden', 'locked', 'locktime',
2453             'needsupdate', 'timecreated', 'timemodified'));
2455         $grades = new backup_nested_element('grade_grades');
2457         $grade = new backup_nested_element('grade_grade', array('id'), array(
2458             'userid', 'rawgrade', 'rawgrademax', 'rawgrademin',
2459             'rawscaleid', 'usermodified', 'finalgrade', 'hidden',
2460             'locked', 'locktime', 'exported', 'overridden',
2461             'excluded', 'feedback', 'feedbackformat', 'information',
2462             'informationformat', 'timecreated', 'timemodified',
2463             'aggregationstatus', 'aggregationweight'));
2465         $letters = new backup_nested_element('grade_letters');
2467         $letter = new backup_nested_element('grade_letter', 'id', array(
2468             'lowerboundary', 'letter'));
2470         // Build the tree
2472         $book->add_child($items);
2473         $items->add_child($item);
2475         $item->add_child($grades);
2476         $grades->add_child($grade);
2478         $book->add_child($letters);
2479         $letters->add_child($letter);
2481         // Define sources
2483         $item->set_source_sql("SELECT gi.*
2484                                FROM {grade_items} gi
2485                                JOIN {backup_ids_temp} bi ON gi.id = bi.itemid
2486                                WHERE bi.backupid = ?
2487                                AND bi.itemname = 'grade_item'", array(backup::VAR_BACKUPID));
2489         // This only happens if we are including user info
2490         if ($userinfo) {
2491             $grade->set_source_table('grade_grades', array('itemid' => backup::VAR_PARENTID));
2492             $grade->annotate_files(GRADE_FILE_COMPONENT, GRADE_FEEDBACK_FILEAREA, 'id');
2493         }
2495         $letter->set_source_table('grade_letters', array('contextid' => backup::VAR_CONTEXTID));
2497         // Annotations
2499         $item->annotate_ids('scalefinal', 'scaleid'); // Straight as scalefinal because it's > 0
2500         $item->annotate_ids('outcome', 'outcomeid');
2502         $grade->annotate_ids('user', 'userid');
2503         $grade->annotate_ids('user', 'usermodified');
2505         // Return the root element (book)
2507         return $book;
2508     }
2511 /**
2512  * Structure step in charge of constructing the grade history of an activity.
2513  *
2514  * This step is added to the task regardless of the setting 'grade_histories'.
2515  * The reason is to allow for a more flexible step in case the logic needs to be
2516  * split accross different settings to control the history of items and/or grades.
2517  */
2518 class backup_activity_grade_history_structure_step extends backup_structure_step {
2520     /**
2521      * No grades on the front page.
2522      * @return bool
2523      */
2524     protected function execute_condition() {
2525         return ($this->get_courseid() != SITEID);
2526     }
2528     protected function define_structure() {
2529         global $CFG;
2531         require_once($CFG->libdir . '/grade/constants.php');
2533         // Settings to use.
2534         $userinfo = $this->get_setting_value('userinfo');
2535         $history = $this->get_setting_value('grade_histories');
2537         // Create the nested elements.
2538         $bookhistory = new backup_nested_element('grade_history');
2539         $grades = new backup_nested_element('grade_grades');
2540         $grade = new backup_nested_element('grade_grade', array('id'), array(
2541             'action', 'oldid', 'source', 'loggeduser', 'itemid', 'userid',
2542             'rawgrade', 'rawgrademax', 'rawgrademin', 'rawscaleid',
2543             'usermodified', 'finalgrade', 'hidden', 'locked', 'locktime', 'exported', 'overridden',
2544             'excluded', 'feedback', 'feedbackformat', 'information',
2545             'informationformat', 'timemodified'));
2547         // Build the tree.
2548         $bookhistory->add_child($grades);
2549         $grades->add_child($grade);
2551         // This only happens if we are including user info and history.
2552         if ($userinfo && $history) {
2553             // Define sources. Only select the history related to existing activity items.
2554             $grade->set_source_sql("SELECT ggh.*
2555                                      FROM {grade_grades_history} ggh
2556                                      JOIN {backup_ids_temp} bi ON ggh.itemid = bi.itemid
2557                                     WHERE bi.backupid = ?
2558                                       AND bi.itemname = 'grade_item'", array(backup::VAR_BACKUPID));
2559             $grade->annotate_files(GRADE_FILE_COMPONENT, GRADE_HISTORY_FEEDBACK_FILEAREA, 'id');
2560         }
2562         // Annotations.
2563         $grade->annotate_ids('scalefinal', 'rawscaleid'); // Straight as scalefinal because it's > 0.
2564         $grade->annotate_ids('user', 'loggeduser');
2565         $grade->annotate_ids('user', 'userid');
2566         $grade->annotate_ids('user', 'usermodified');
2568         // Return the root element.
2569         return $bookhistory;
2570     }
2573 /**
2574  * Backups up the course completion information for the course.
2575  */
2576 class backup_course_completion_structure_step extends backup_structure_step {
2578     protected function execute_condition() {
2580         // No completion on front page.
2581         if ($this->get_courseid() == SITEID) {
2582             return false;
2583         }
2585         // Check that all activities have been included
2586         if ($this->task->is_excluding_activities()) {
2587             return false;
2588         }
2589         return true;
2590     }
2592     /**
2593      * The structure of the course completion backup
2594      *
2595      * @return backup_nested_element
2596      */
2597     protected function define_structure() {
2599         // To know if we are including user completion info
2600         $userinfo = $this->get_setting_value('userscompletion');
2602         $cc = new backup_nested_element('course_completion');
2604         $criteria = new backup_nested_element('course_completion_criteria', array('id'), array(
2605             'course', 'criteriatype', 'module', 'moduleinstance', 'courseinstanceshortname', 'enrolperiod',
2606             'timeend', 'gradepass', 'role', 'roleshortname'
2607         ));
2609         $criteriacompletions = new backup_nested_element('course_completion_crit_completions');
2611         $criteriacomplete = new backup_nested_element('course_completion_crit_compl', array('id'), array(
2612             'criteriaid', 'userid', 'gradefinal', 'unenrolled', 'timecompleted'
2613         ));
2615         $coursecompletions = new backup_nested_element('course_completions', array('id'), array(
2616             'userid', 'course', 'timeenrolled', 'timestarted', 'timecompleted', 'reaggregate'
2617         ));
2619         $aggregatemethod = new backup_nested_element('course_completion_aggr_methd', array('id'), array(
2620             'course','criteriatype','method','value'
2621         ));
2623         $cc->add_child($criteria);
2624             $criteria->add_child($criteriacompletions);
2625                 $criteriacompletions->add_child($criteriacomplete);
2626         $cc->add_child($coursecompletions);
2627         $cc->add_child($aggregatemethod);
2629         // We need some extra data for the restore.
2630         // - courseinstances shortname rather than an ID.
2631         // - roleshortname in case restoring on a different site.
2632         $sourcesql = "SELECT ccc.*, c.shortname AS courseinstanceshortname, r.shortname AS roleshortname
2633                         FROM {course_completion_criteria} ccc
2634                    LEFT JOIN {course} c ON c.id = ccc.courseinstance
2635                    LEFT JOIN {role} r ON r.id = ccc.role
2636                        WHERE ccc.course = ?";
2637         $criteria->set_source_sql($sourcesql, array(backup::VAR_COURSEID));
2639         $aggregatemethod->set_source_table('course_completion_aggr_methd', array('course' => backup::VAR_COURSEID));
2641         if ($userinfo) {
2642             $criteriacomplete->set_source_table('course_completion_crit_compl', array('criteriaid' => backup::VAR_PARENTID));
2643             $coursecompletions->set_source_table('course_completions', array('course' => backup::VAR_COURSEID));
2644         }
2646         $criteria->annotate_ids('role', 'role');
2647         $criteriacomplete->annotate_ids('user', 'userid');
2648         $coursecompletions->annotate_ids('user', 'userid');
2650         return $cc;
2652     }
2655 /**
2656  * Backup completion defaults for each module type.
2657  *
2658  * @package     core_backup
2659  * @copyright   2017 Marina Glancy
2660  * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2661  */
2662 class backup_completion_defaults_structure_step extends backup_structure_step {
2664     /**
2665      * To conditionally decide if one step will be executed or no
2666      */
2667     protected function execute_condition() {
2668         // No completion on front page.
2669         if ($this->get_courseid() == SITEID) {
2670             return false;
2671         }
2672         return true;
2673     }
2675     /**
2676      * The structure of the course completion backup
2677      *
2678      * @return backup_nested_element
2679      */
2680     protected function define_structure() {
2682         $cc = new backup_nested_element('course_completion_defaults');
2684         $defaults = new backup_nested_element('course_completion_default', array('id'), array(
2685             'modulename', 'completion', 'completionview', 'completionusegrade', 'completionexpected', 'customrules'
2686         ));
2688         // Use module name instead of module id so we can insert into another site later.
2689         $sourcesql = "SELECT d.id, m.name as modulename, d.completion, d.completionview, d.completionusegrade,
2690                   d.completionexpected, d.customrules
2691                 FROM {course_completion_defaults} d join {modules} m on d.module = m.id
2692                 WHERE d.course = ?";
2693         $defaults->set_source_sql($sourcesql, array(backup::VAR_COURSEID));
2695         $cc->add_child($defaults);
2696         return $cc;
2698     }