Merge branch 'MDL-40566_master' of git://github.com/dmonllao/moodle
[moodle.git] / backup / util / dbops / backup_controller_dbops.class.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * @package    moodlecore
20  * @subpackage backup-dbops
21  * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 /**
26  * Non instantiable helper class providing DB support to the @backup_controller
27  *
28  * This class contains various static methods available for all the DB operations
29  * performed by the backup_controller class
30  *
31  * TODO: Finish phpdocs
32  */
33 abstract class backup_controller_dbops extends backup_dbops {
35     /**
36      * Send one backup controller to DB
37      *
38      * @param backup_controller $controller controller to send to DB
39      * @param string $checksum hash of the controller to be checked
40      * @param bool $includeobj to decide if the object itself must be updated (true) or no (false)
41      * @param bool $cleanobj to decide if the object itself must be cleaned (true) or no (false)
42      * @return int id of the controller record in the DB
43      * @throws backup_controller_exception|backup_dbops_exception
44      */
45     public static function save_controller($controller, $checksum, $includeobj = true, $cleanobj = false) {
46         global $DB;
47         // Check we are going to save one backup_controller
48         if (! $controller instanceof backup_controller) {
49             throw new backup_controller_exception('backup_controller_expected');
50         }
51         // Check checksum is ok. Only if we are including object info. Sounds silly but it isn't ;-).
52         if ($includeobj and !$controller->is_checksum_correct($checksum)) {
53             throw new backup_dbops_exception('backup_controller_dbops_saving_checksum_mismatch');
54         }
55         // Cannot request to $includeobj and $cleanobj at the same time.
56         if ($includeobj and $cleanobj) {
57             throw new backup_dbops_exception('backup_controller_dbops_saving_cannot_include_and_delete');
58         }
59         // Get all the columns
60         $rec = new stdclass();
61         $rec->backupid     = $controller->get_backupid();
62         $rec->operation    = $controller->get_operation();
63         $rec->type         = $controller->get_type();
64         $rec->itemid       = $controller->get_id();
65         $rec->format       = $controller->get_format();
66         $rec->interactive  = $controller->get_interactive();
67         $rec->purpose      = $controller->get_mode();
68         $rec->userid       = $controller->get_userid();
69         $rec->status       = $controller->get_status();
70         $rec->execution    = $controller->get_execution();
71         $rec->executiontime= $controller->get_executiontime();
72         $rec->checksum     = $checksum;
73         // Serialize information
74         if ($includeobj) {
75             $rec->controller = base64_encode(serialize($controller));
76         } else if ($cleanobj) {
77             $rec->controller = '';
78         }
79         // Send it to DB
80         if ($recexists = $DB->get_record('backup_controllers', array('backupid' => $rec->backupid))) {
81             $rec->id = $recexists->id;
82             $rec->timemodified = time();
83             $DB->update_record('backup_controllers', $rec);
84         } else {
85             $rec->timecreated = time();
86             $rec->timemodified = 0;
87             $rec->id = $DB->insert_record('backup_controllers', $rec);
88         }
89         return $rec->id;
90     }
92     public static function load_controller($backupid) {
93         global $DB;
94         if (! $controllerrec = $DB->get_record('backup_controllers', array('backupid' => $backupid))) {
95             throw new backup_dbops_exception('backup_controller_dbops_nonexisting');
96         }
97         $controller = unserialize(base64_decode($controllerrec->controller));
98         // Check checksum is ok. Sounds silly but it isn't ;-)
99         if (!$controller->is_checksum_correct($controllerrec->checksum)) {
100             throw new backup_dbops_exception('backup_controller_dbops_loading_checksum_mismatch');
101         }
102         return $controller;
103     }
105     public static function create_backup_ids_temp_table($backupid) {
106         global $CFG, $DB;
107         $dbman = $DB->get_manager(); // We are going to use database_manager services
109         $xmldb_table = new xmldb_table('backup_ids_temp');
110         $xmldb_table->add_field('id', XMLDB_TYPE_INTEGER, '10', null, XMLDB_NOTNULL, XMLDB_SEQUENCE, null);
111         // Set default backupid (not needed but this enforce any missing backupid). That's hackery in action!
112         $xmldb_table->add_field('backupid', XMLDB_TYPE_CHAR, 32, null, XMLDB_NOTNULL, null, $backupid);
113         $xmldb_table->add_field('itemname', XMLDB_TYPE_CHAR, 160, null, XMLDB_NOTNULL, null, null);
114         $xmldb_table->add_field('itemid', XMLDB_TYPE_INTEGER, 10, null, XMLDB_NOTNULL, null, null);
115         $xmldb_table->add_field('newitemid', XMLDB_TYPE_INTEGER, 10, null, XMLDB_NOTNULL, null, '0');
116         $xmldb_table->add_field('parentitemid', XMLDB_TYPE_INTEGER, 10, null, null, null, null);
117         $xmldb_table->add_field('info', XMLDB_TYPE_TEXT, null, null, null, null, null);
118         $xmldb_table->add_key('primary', XMLDB_KEY_PRIMARY, array('id'));
119         $xmldb_table->add_key('backupid_itemname_itemid_uk', XMLDB_KEY_UNIQUE, array('backupid','itemname','itemid'));
120         $xmldb_table->add_index('backupid_parentitemid_ix', XMLDB_INDEX_NOTUNIQUE, array('backupid','itemname','parentitemid'));
121         $xmldb_table->add_index('backupid_itemname_newitemid_ix', XMLDB_INDEX_NOTUNIQUE, array('backupid','itemname','newitemid'));
123         $dbman->create_temp_table($xmldb_table); // And create it
125     }
127     public static function create_backup_files_temp_table($backupid) {
128         global $CFG, $DB;
129         $dbman = $DB->get_manager(); // We are going to use database_manager services
131         $xmldb_table = new xmldb_table('backup_files_temp');
132         $xmldb_table->add_field('id', XMLDB_TYPE_INTEGER, '10', null, XMLDB_NOTNULL, XMLDB_SEQUENCE, null);
133         // Set default backupid (not needed but this enforce any missing backupid). That's hackery in action!
134         $xmldb_table->add_field('backupid', XMLDB_TYPE_CHAR, 32, null, XMLDB_NOTNULL, null, $backupid);
135         $xmldb_table->add_field('contextid', XMLDB_TYPE_INTEGER, 10, null, XMLDB_NOTNULL, null, null);
136         $xmldb_table->add_field('component', XMLDB_TYPE_CHAR, 100, null, XMLDB_NOTNULL, null, null);
137         $xmldb_table->add_field('filearea', XMLDB_TYPE_CHAR, 50, null, XMLDB_NOTNULL, null, null);
138         $xmldb_table->add_field('itemid', XMLDB_TYPE_INTEGER, 10, null, XMLDB_NOTNULL, null, null);
139         $xmldb_table->add_field('info', XMLDB_TYPE_TEXT, null, null, null, null, null);
140         $xmldb_table->add_field('newcontextid', XMLDB_TYPE_INTEGER, 10, null, null, null, null);
141         $xmldb_table->add_field('newitemid', XMLDB_TYPE_INTEGER, 10, null, null, null, null);
142         $xmldb_table->add_key('primary', XMLDB_KEY_PRIMARY, array('id'));
143         $xmldb_table->add_index('backupid_contextid_component_filearea_itemid_ix', XMLDB_INDEX_NOTUNIQUE, array('backupid','contextid','component','filearea','itemid'));
145         $dbman->create_temp_table($xmldb_table); // And create it
146     }
148     public static function drop_backup_ids_temp_table($backupid) {
149         global $DB;
150         $dbman = $DB->get_manager(); // We are going to use database_manager services
152         $targettablename = 'backup_ids_temp';
153         $table = new xmldb_table($targettablename);
154         $dbman->drop_table($table); // And drop it
155     }
157     /**
158      * Decode the info field from backup_ids_temp or backup_files_temp.
159      *
160      * @param mixed $info The info field data to decode, may be an object or a simple integer.
161      * @return mixed The decoded information.  For simple types it returns, for complex ones we decode.
162      */
163     public static function decode_backup_temp_info($info) {
164         // We encode all data except null.
165         if ($info != null) {
166             if (extension_loaded('zlib')) {
167                 return unserialize(gzuncompress(base64_decode($info)));
168             } else {
169                 return unserialize(base64_decode($info));
170             }
171         }
172         return $info;
173     }
175     /**
176      * Encode the info field for backup_ids_temp or backup_files_temp.
177      *
178      * @param mixed $info string The info field data to encode.
179      * @return string An encoded string of data or null if the input is null.
180      */
181     public static function encode_backup_temp_info($info) {
182         // We encode if there is any information to keep the translations simpler.
183         if ($info != null) {
184             // We compress if possible. It reduces db, network and memory storage. The saving is greater than CPU compression cost.
185             // Compression level 1 is chosen has it produces good compression with the smallest possible overhead, see MDL-40618.
186             if (extension_loaded('zlib')) {
187                 return base64_encode(gzcompress(serialize($info), 1));
188             } else {
189                 return base64_encode(serialize($info));
190             }
191         }
192         return $info;
193     }
195     /**
196      * Given one type and id from controller, return the corresponding courseid
197      */
198     public static function get_courseid_from_type_id($type, $id) {
199         global $DB;
200         if ($type == backup::TYPE_1COURSE) {
201             return $id; // id is the course id
203         } else if ($type == backup::TYPE_1SECTION) {
204             if (! $courseid = $DB->get_field('course_sections', 'course', array('id' => $id))) {
205                 throw new backup_dbops_exception('course_not_found_for_section', $id);
206             }
207             return $courseid;
208         } else if ($type == backup::TYPE_1ACTIVITY) {
209             if (! $courseid = $DB->get_field('course_modules', 'course', array('id' => $id))) {
210                 throw new backup_dbops_exception('course_not_found_for_moduleid', $id);
211             }
212             return $courseid;
213         }
214     }
216     /**
217      * Given one activity task, return the activity information and related settings
218      * Used by get_moodle_backup_information()
219      */
220     private static function get_activity_backup_information($task) {
222         $contentinfo = array(
223             'moduleid'   => $task->get_moduleid(),
224             'sectionid'  => $task->get_sectionid(),
225             'modulename' => $task->get_modulename(),
226             'title'      => $task->get_name(),
227             'directory'  => 'activities/' . $task->get_modulename() . '_' . $task->get_moduleid());
229         // Now get activity settings
230         // Calculate prefix to find valid settings
231         $prefix = basename($contentinfo['directory']);
232         $settingsinfo = array();
233         foreach ($task->get_settings() as $setting) {
234             // Discard ones without valid prefix
235             if (strpos($setting->get_name(), $prefix) !== 0) {
236                 continue;
237             }
238             // Validate level is correct (activity)
239             if ($setting->get_level() != backup_setting::ACTIVITY_LEVEL) {
240                 throw new backup_controller_exception('setting_not_activity_level', $setting);
241             }
242             $settinginfo = array(
243                 'level'    => 'activity',
244                 'activity' => $prefix,
245                 'name'     => $setting->get_name(),
246                 'value'    => $setting->get_value());
247             $settingsinfo[$setting->get_name()] = (object)$settinginfo;
248         }
249         return array($contentinfo, $settingsinfo);
250     }
252     /**
253      * Given one section task, return the section information and related settings
254      * Used by get_moodle_backup_information()
255      */
256     private static function get_section_backup_information($task) {
258         $contentinfo = array(
259             'sectionid'  => $task->get_sectionid(),
260             'title'      => $task->get_name(),
261             'directory'  => 'sections/' . 'section_' . $task->get_sectionid());
263         // Now get section settings
264         // Calculate prefix to find valid settings
265         $prefix = basename($contentinfo['directory']);
266         $settingsinfo = array();
267         foreach ($task->get_settings() as $setting) {
268             // Discard ones without valid prefix
269             if (strpos($setting->get_name(), $prefix) !== 0) {
270                 continue;
271             }
272             // Validate level is correct (section)
273             if ($setting->get_level() != backup_setting::SECTION_LEVEL) {
274                 throw new backup_controller_exception('setting_not_section_level', $setting);
275             }
276             $settinginfo = array(
277                 'level'    => 'section',
278                 'section'  => $prefix,
279                 'name'     => $setting->get_name(),
280                 'value'    => $setting->get_value());
281             $settingsinfo[$setting->get_name()] = (object)$settinginfo;
282         }
283         return array($contentinfo, $settingsinfo);
284     }
286     /**
287      * Given one course task, return the course information and related settings
288      * Used by get_moodle_backup_information()
289      */
290     private static function get_course_backup_information($task) {
292         $contentinfo = array(
293             'courseid'   => $task->get_courseid(),
294             'title'      => $task->get_name(),
295             'directory'  => 'course');
297         // Now get course settings
298         // Calculate prefix to find valid settings
299         $prefix = basename($contentinfo['directory']);
300         $settingsinfo = array();
301         foreach ($task->get_settings() as $setting) {
302             // Discard ones without valid prefix
303             if (strpos($setting->get_name(), $prefix) !== 0) {
304                 continue;
305             }
306             // Validate level is correct (course)
307             if ($setting->get_level() != backup_setting::COURSE_LEVEL) {
308                 throw new backup_controller_exception('setting_not_course_level', $setting);
309             }
310             $settinginfo = array(
311                 'level'    => 'course',
312                 'name'     => $setting->get_name(),
313                 'value'    => $setting->get_value());
314             $settingsinfo[$setting->get_name()] = (object)$settinginfo;
315         }
316         return array($contentinfo, $settingsinfo);
317     }
319     /**
320      * Given one root task, return the course information and related settings
321      * Used by get_moodle_backup_information()
322      */
323     private static function get_root_backup_information($task) {
325         // Now get root settings
326         $settingsinfo = array();
327         foreach ($task->get_settings() as $setting) {
328             // Validate level is correct (root)
329             if ($setting->get_level() != backup_setting::ROOT_LEVEL) {
330                 throw new backup_controller_exception('setting_not_root_level', $setting);
331             }
332             $settinginfo = array(
333                 'level'    => 'root',
334                 'name'     => $setting->get_name(),
335                 'value'    => $setting->get_value());
336             $settingsinfo[$setting->get_name()] = (object)$settinginfo;
337         }
338         return array(null, $settingsinfo);
339     }
341     /**
342      * Get details information for main moodle_backup.xml file, extracting it from
343      * the specified controller
344      */
345     public static function get_moodle_backup_information($backupid) {
347         $detailsinfo = array(); // Information details
348         $contentsinfo= array(); // Information about backup contents
349         $settingsinfo= array(); // Information about backup settings
350         $bc = self::load_controller($backupid); // Load controller
352         // Details info
353         $detailsinfo['id'] = $bc->get_id();
354         $detailsinfo['backup_id'] = $bc->get_backupid();
355         $detailsinfo['type'] = $bc->get_type();
356         $detailsinfo['format'] = $bc->get_format();
357         $detailsinfo['interactive'] = $bc->get_interactive();
358         $detailsinfo['mode'] = $bc->get_mode();
359         $detailsinfo['execution'] = $bc->get_execution();
360         $detailsinfo['executiontime'] = $bc->get_executiontime();
361         $detailsinfo['userid'] = $bc->get_userid();
362         $detailsinfo['courseid'] = $bc->get_courseid();
365         // Init content placeholders
366         $contentsinfo['activities'] = array();
367         $contentsinfo['sections']   = array();
368         $contentsinfo['course']     = array();
370         // Contents info (extract information from tasks)
371         foreach ($bc->get_plan()->get_tasks() as $task) {
373             if ($task instanceof backup_activity_task) { // Activity task
375                 if ($task->get_setting_value('included')) { // Only return info about included activities
376                     list($contentinfo, $settings) = self::get_activity_backup_information($task);
377                     $contentsinfo['activities'][] = $contentinfo;
378                     $settingsinfo = array_merge($settingsinfo, $settings);
379                 }
381             } else if ($task instanceof backup_section_task) { // Section task
383                 if ($task->get_setting_value('included')) { // Only return info about included sections
384                     list($contentinfo, $settings) = self::get_section_backup_information($task);
385                     $contentsinfo['sections'][] = $contentinfo;
386                     $settingsinfo = array_merge($settingsinfo, $settings);
387                 }
389             } else if ($task instanceof backup_course_task) { // Course task
391                 list($contentinfo, $settings) = self::get_course_backup_information($task);
392                 $contentsinfo['course'][] = $contentinfo;
393                 $settingsinfo = array_merge($settingsinfo, $settings);
395             } else if ($task instanceof backup_root_task) { // Root task
397                 list($contentinfo, $settings) = self::get_root_backup_information($task);
398                 $settingsinfo = array_merge($settingsinfo, $settings);
399             }
400         }
402         $bc->destroy(); // Always need to destroy controller to handle circular references
404         return array(array((object)$detailsinfo), $contentsinfo, $settingsinfo);
405     }
407     /**
408      * Update CFG->backup_version and CFG->backup_release if change in
409      * version is detected.
410      */
411     public static function apply_version_and_release() {
412         global $CFG;
414         if ($CFG->backup_version < backup::VERSION) {
415             set_config('backup_version', backup::VERSION);
416             set_config('backup_release', backup::RELEASE);
417         }
418     }
420     /**
421      * Given the backupid, detect if the backup includes "mnet" remote users or no
422      */
423     public static function backup_includes_mnet_remote_users($backupid) {
424         global $CFG, $DB;
426         $sql = "SELECT COUNT(*)
427                   FROM {backup_ids_temp} b
428                   JOIN {user} u ON u.id = b.itemid
429                  WHERE b.backupid = ?
430                    AND b.itemname = 'userfinal'
431                    AND u.mnethostid != ?";
432         $count = $DB->count_records_sql($sql, array($backupid, $CFG->mnet_localhost_id));
433         return (int)(bool)$count;
434     }
436     /**
437      * Given the backupid, determine whether this backup should include
438      * files from the moodle file storage system.
439      *
440      * @param string $backupid The ID of the backup.
441      * @return int Indicates whether files should be included in backups.
442      */
443     public static function backup_includes_files($backupid) {
444         // Load controller
445         $bc = self::load_controller($backupid);
446         return $bc->get_include_files();
447     }
449     /**
450      * Given the backupid, detect if the backup contains references to external contents
451      *
452      * @copyright 2012 Dongsheng Cai {@link http://dongsheng.org}
453      * @return int
454      */
455     public static function backup_includes_file_references($backupid) {
456         global $CFG, $DB;
458         $sql = "SELECT count(r.repositoryid)
459                   FROM {files} f
460                   LEFT JOIN {files_reference} r
461                        ON r.id = f.referencefileid
462                   JOIN {backup_ids_temp} bi
463                        ON f.id = bi.itemid
464                  WHERE bi.backupid = ?
465                        AND bi.itemname = 'filefinal'";
466         $count = $DB->count_records_sql($sql, array($backupid));
467         return (int)(bool)$count;
468     }
470     /**
471      * Given the courseid, return some course related information we want to transport
472      *
473      * @param int $course the id of the course this backup belongs to
474      */
475     public static function backup_get_original_course_info($courseid) {
476         global $DB;
477         return $DB->get_record('course', array('id' => $courseid), 'fullname, shortname, startdate');
478     }
480     /**
481      * Sets the default values for the settings in a backup operation
482      *
483      * Based on the mode of the backup it will delegate the process to
484      * other methods like {@link apply_general_config_defaults} ...
485      * to get proper defaults loaded
486      *
487      * @param backup_controller $controller
488      */
489     public static function apply_config_defaults(backup_controller $controller) {
490         // Based on the mode of the backup (general, automated, import, hub...)
491         // decide the action to perform to get defaults loaded
492         $mode = $controller->get_mode();
494         switch ($mode) {
495             case backup::MODE_GENERAL:
496                 // Load the general defaults
497                 self::apply_general_config_defaults($controller);
498                 break;
499             case backup::MODE_AUTOMATED:
500                 // TODO: Move the loading from automatic stuff to here
501                 break;
502             default:
503                 // Nothing to do for other modes (IMPORT/HUB...). Some day we
504                 // can define defaults (admin UI...) for them if we want to
505         }
506     }
508     /**
509      * Sets the controller settings default values from the backup config.
510      *
511      * @param backup_controller $controller
512      */
513     private static function apply_general_config_defaults(backup_controller $controller) {
514         $settings = array(
515             // Config name                      => Setting name
516             'backup_general_users'              => 'users',
517             'backup_general_anonymize'          => 'anonymize',
518             'backup_general_role_assignments'   => 'role_assignments',
519             'backup_general_activities'         => 'activities',
520             'backup_general_blocks'             => 'blocks',
521             'backup_general_filters'            => 'filters',
522             'backup_general_comments'           => 'comments',
523             'backup_general_badges'             => 'badges',
524             'backup_general_userscompletion'    => 'userscompletion',
525             'backup_general_logs'               => 'logs',
526             'backup_general_histories'          => 'grade_histories'
527         );
528         $plan = $controller->get_plan();
529         foreach ($settings as $config=>$settingname) {
530             $value = get_config('backup', $config);
531             $locked = (get_config('backup', $config.'_locked') == true);
532             if ($plan->setting_exists($settingname)) {
533                 $setting = $plan->get_setting($settingname);
534                 if ($setting->get_value() != $value || 1==1) {
535                     $setting->set_value($value);
536                     if ($locked) {
537                         $setting->set_status(base_setting::LOCKED_BY_CONFIG);
538                     }
539                 }
540             }
541         }
542     }