Merge branch 'MDL-62572-master' of git://github.com/damyon/moodle
[moodle.git] / backup / controller / restore_controller.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-controller
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  * Class implementing the controller of any restore process
27  *
28  * This final class is in charge of controlling all the restore architecture, for any
29  * type of backup.
30  *
31  * TODO: Finish phpdocs
32  */
33 class restore_controller extends base_controller {
35     protected $tempdir;   // Directory under $CFG->backuptempdir awaiting restore
36     protected $restoreid; // Unique identificator for this restore
38     protected $courseid; // courseid where restore is going to happen
40     protected $type;   // Type of backup (activity, section, course)
41     protected $format; // Format of backup (moodle, imscc)
42     protected $interactive; // yes/no
43     protected $mode;   // Purpose of the backup (default settings)
44     protected $userid; // user id executing the restore
45     protected $operation; // Type of operation (backup/restore)
46     protected $target;    // Restoring to new/existing/current_adding/_deleting
47     protected $samesite;  // Are we restoring to the same site where the backup was generated
49     protected $status; // Current status of the controller (created, planned, configured...)
50     protected $precheck;    // Results of the execution of restore prechecks
52     protected $info;   // Information retrieved from backup contents
53     /** @var restore_plan */
54     protected $plan;   // Restore execution plan
56     /**
57      * Immediate/delayed execution type.
58      * @var integer
59      */
60     protected $execution;
61     protected $executiontime; // epoch time when we want the restore to be executed (requires cron to run)
63     protected $checksum; // Cache @checksumable results for lighter @is_checksum_correct() uses
65     /** @var int Number of restore_controllers that are currently executing */
66     protected static $executing = 0;
68     /**
69      * Constructor.
70      *
71      * If you specify a progress monitor, this will be used to report progress
72      * while loading the plan, as well as for future use. (You can change it
73      * for a different one later using set_progress.)
74      *
75      * @param string $tempdir Directory under $CFG->backuptempdir awaiting restore
76      * @param int $courseid Course id where restore is going to happen
77      * @param bool $interactive backup::INTERACTIVE_YES[true] or backup::INTERACTIVE_NO[false]
78      * @param int $mode backup::MODE_[ GENERAL | HUB | IMPORT | SAMESITE ]
79      * @param int $userid
80      * @param int $target backup::TARGET_[ NEW_COURSE | CURRENT_ADDING | CURRENT_DELETING | EXISTING_ADDING | EXISTING_DELETING ]
81      * @param \core\progress\base $progress Optional progress monitor
82      */
83     public function __construct($tempdir, $courseid, $interactive, $mode, $userid, $target,
84             \core\progress\base $progress = null) {
85         $this->tempdir = $tempdir;
86         $this->courseid = $courseid;
87         $this->interactive = $interactive;
88         $this->mode = $mode;
89         $this->userid = $userid;
90         $this->target = $target;
92         // Apply some defaults
93         $this->type = '';
94         $this->format = backup::FORMAT_UNKNOWN;
95         $this->operation = backup::OPERATION_RESTORE;
96         $this->executiontime = 0;
97         $this->samesite = false;
98         $this->checksum = '';
99         $this->precheck = null;
101         // Apply current backup version and release if necessary
102         backup_controller_dbops::apply_version_and_release();
104         // Check courseid is correct
105         restore_check::check_courseid($this->courseid);
107         // Check user is correct
108         restore_check::check_user($this->userid);
110         // Calculate unique $restoreid
111         $this->calculate_restoreid();
113         // Default logger chain (based on interactive/execution)
114         $this->logger = backup_factory::get_logger_chain($this->interactive, $this->execution, $this->restoreid);
116         // Set execution based on backup mode.
117         if ($mode == backup::MODE_ASYNC) {
118             $this->execution = backup::EXECUTION_DELAYED;
119         } else {
120             $this->execution = backup::EXECUTION_INMEDIATE;
121         }
123         // By default there is no progress reporter unless you specify one so it
124         // can be used during loading of the plan.
125         if ($progress) {
126             $this->progress = $progress;
127         } else {
128             $this->progress = new \core\progress\none();
129         }
130         $this->progress->start_progress('Constructing restore_controller');
132         // Instantiate the output_controller singleton and active it if interactive and immediate.
133         $oc = output_controller::get_instance();
134         if ($this->interactive == backup::INTERACTIVE_YES && $this->execution == backup::EXECUTION_INMEDIATE) {
135             $oc->set_active(true);
136         }
138         $this->log('instantiating restore controller', backup::LOG_INFO, $this->restoreid);
140         // Set initial status
141         $this->set_status(backup::STATUS_CREATED);
143         // Calculate original restore format
144         $this->format = backup_general_helper::detect_backup_format($tempdir);
146         // If format is not moodle2, set to conversion needed
147         if ($this->format !== backup::FORMAT_MOODLE) {
148             $this->set_status(backup::STATUS_REQUIRE_CONV);
150         // Else, format is moodle2, load plan, apply security and set status based on interactivity
151         } else {
152             // Load plan
153             $this->load_plan();
155             // Apply all default settings (based on type/format/mode).
156             $this->apply_defaults();
158             // Perform all initial security checks and apply (2nd param) them to settings automatically
159             restore_check::check_security($this, true);
161             if ($this->interactive == backup::INTERACTIVE_YES) {
162                 $this->set_status(backup::STATUS_SETTING_UI);
163             } else {
164                 $this->set_status(backup::STATUS_NEED_PRECHECK);
165             }
166         }
168         // Tell progress monitor that we finished loading.
169         $this->progress->end_progress();
170     }
172     /**
173      * Clean structures used by the restore_controller
174      *
175      * This method clean various structures used by the restore_controller,
176      * destroying them in an ordered way, so their memory will be gc properly
177      * by PHP (mainly circular references).
178      *
179      * Note that, while it's not mandatory to execute this method, it's highly
180      * recommended to do so, specially in scripts performing multiple operations
181      * (like the automated backups) or the system will run out of memory after
182      * a few dozens of backups)
183      */
184     public function destroy() {
185         // Only need to destroy circulars under the plan. Delegate to it.
186         $this->plan->destroy();
187         // Loggers may have also chained references, destroy them. Also closing resources when needed.
188         $this->logger->destroy();
189     }
191     public function finish_ui() {
192         if ($this->status != backup::STATUS_SETTING_UI) {
193             throw new restore_controller_exception('cannot_finish_ui_if_not_setting_ui');
194         }
195         $this->set_status(backup::STATUS_NEED_PRECHECK);
196     }
198     public function process_ui_event() {
200         // Perform security checks throwing exceptions (2nd param) if something is wrong
201         restore_check::check_security($this, false);
202     }
204     public function set_status($status) {
205         // Note: never save_controller() with the object info after STATUS_EXECUTING or the whole controller,
206         // containing all the steps will be sent to DB. 100% (monster) useless.
207         $this->log('setting controller status to', backup::LOG_DEBUG, $status);
208         // TODO: Check it's a correct status.
209         $this->status = $status;
210         // Ensure that, once set to backup::STATUS_AWAITING | STATUS_NEED_PRECHECK, controller is stored in DB.
211         // Also save if executing so we can better track progress.
212         if ($status == backup::STATUS_AWAITING || $status == backup::STATUS_NEED_PRECHECK || $status == backup::STATUS_EXECUTING) {
213             $this->save_controller();
214             $tbc = self::load_controller($this->restoreid);
215             $this->logger = $tbc->logger; // wakeup loggers
216             $tbc->plan->destroy(); // Clean plan controller structures, keeping logger alive.
218         } else if ($status == backup::STATUS_FINISHED_OK) {
219             // If the operation has ended without error (backup::STATUS_FINISHED_OK)
220             // proceed by cleaning the object from database. MDL-29262.
221             $this->save_controller(false, true);
222         } else if ($status == backup::STATUS_FINISHED_ERR) {
223             // If the operation has ended with an error save the controller
224             // preserving the object in the database. We may want it for debugging.
225             $this->save_controller();
226         }
227     }
229     public function set_execution($execution, $executiontime = 0) {
230         $this->log('setting controller execution', backup::LOG_DEBUG);
231         // TODO: Check valid execution mode.
232         // TODO: Check time in future.
233         // TODO: Check time = 0 if immediate.
234         $this->execution = $execution;
235         $this->executiontime = $executiontime;
237         // Default logger chain (based on interactive/execution)
238         $this->logger = backup_factory::get_logger_chain($this->interactive, $this->execution, $this->restoreid);
239     }
241 // checksumable interface methods
243     public function calculate_checksum() {
244         // Reset current checksum to take it out from calculations!
245         $this->checksum = '';
246         // Init checksum
247         $tempchecksum = md5('tempdir-'    . $this->tempdir .
248                             'restoreid-'  . $this->restoreid .
249                             'courseid-'   . $this->courseid .
250                             'type-'       . $this->type .
251                             'format-'     . $this->format .
252                             'interactive-'. $this->interactive .
253                             'mode-'       . $this->mode .
254                             'userid-'     . $this->userid .
255                             'target-'     . $this->target .
256                             'samesite-'   . $this->samesite .
257                             'operation-'  . $this->operation .
258                             'status-'     . $this->status .
259                             'precheck-'   . backup_general_helper::array_checksum_recursive(array($this->precheck)) .
260                             'execution-'  . $this->execution .
261                             'plan-'       . backup_general_helper::array_checksum_recursive(array($this->plan)) .
262                             'info-'       . backup_general_helper::array_checksum_recursive(array($this->info)) .
263                             'logger-'     . backup_general_helper::array_checksum_recursive(array($this->logger)));
264         $this->log('calculating controller checksum', backup::LOG_DEBUG, $tempchecksum);
265         return $tempchecksum;
266     }
268     public function is_checksum_correct($checksum) {
269         return $this->checksum === $checksum;
270     }
272     public function get_tempdir() {
273         return $this->tempdir;
274     }
276     public function get_restoreid() {
277         return $this->restoreid;
278     }
280     public function get_type() {
281         return $this->type;
282     }
284     public function get_operation() {
285         return $this->operation;
286     }
288     public function get_courseid() {
289         return $this->courseid;
290     }
292     public function get_format() {
293         return $this->format;
294     }
296     public function get_interactive() {
297         return $this->interactive;
298     }
300     public function get_mode() {
301         return $this->mode;
302     }
304     public function get_userid() {
305         return $this->userid;
306     }
308     public function get_target() {
309         return $this->target;
310     }
312     public function is_samesite() {
313         return $this->samesite;
314     }
316     public function get_status() {
317         return $this->status;
318     }
320     public function get_execution() {
321         return $this->execution;
322     }
324     public function get_executiontime() {
325         return $this->executiontime;
326     }
328     /**
329      * Returns the restore plan
330      * @return restore_plan
331      */
332     public function get_plan() {
333         return $this->plan;
334     }
336     public function get_info() {
337         return $this->info;
338     }
340     public function execute_plan() {
341         // Basic/initial prevention against time/memory limits
342         core_php_time_limit::raise(1 * 60 * 60); // 1 hour for 1 course initially granted
343         raise_memory_limit(MEMORY_EXTRA);
344         // If this is not a course restore or single activity restore (e.g. duplicate), inform the plan we are not
345         // including all the activities for sure. This will affect any
346         // task/step executed conditionally to stop processing information
347         // for section and activity restore. MDL-28180.
348         if ($this->get_type() !== backup::TYPE_1COURSE && $this->get_type() !== backup::TYPE_1ACTIVITY) {
349             $this->log('notifying plan about excluded activities by type', backup::LOG_DEBUG);
350             $this->plan->set_excluding_activities();
351         }
352         self::$executing++;
353         try {
354             $this->plan->execute();
355         } catch (Exception $e) {
356             self::$executing--;
357             throw $e;
358         }
359         self::$executing--;
360     }
362     /**
363      * Checks whether restore is currently executing. Certain parts of code that
364      * is called during restore, but not directly part of the restore system, may
365      * need to behave differently during restore (e.g. do not bother resetting a
366      * cache because we know it will be reset at end of operation).
367      *
368      * @return bool True if any restore is currently executing
369      */
370     public static function is_executing() {
371         return self::$executing > 0;
372     }
374     /**
375      * Execute the restore prechecks to detect any problem before proceed with restore
376      *
377      * This function checks various parts of the restore (versions, users, roles...)
378      * returning true if everything was ok or false if any warning/error was detected.
379      * Any warning/error is returned by the get_precheck_results() method.
380      * Note: if any problem is found it will, automatically, drop all the restore temp
381      * tables as far as the next step is to inform about the warning/errors. If no problem
382      * is found, then default behaviour is to keep the temp tables so, in the same request
383      * restore will be executed, saving a lot of checks to be executed again.
384      * Note: If for any reason (UI to show after prechecks...) you want to force temp tables
385      * to be dropped always, you can pass true to the $droptemptablesafter parameter
386      */
387     public function execute_precheck($droptemptablesafter = false) {
388         if (is_array($this->precheck)) {
389             throw new restore_controller_exception('precheck_alredy_executed', $this->status);
390         }
391         if ($this->status != backup::STATUS_NEED_PRECHECK) {
392             throw new restore_controller_exception('cannot_precheck_wrong_status', $this->status);
393         }
394         // Basic/initial prevention against time/memory limits
395         core_php_time_limit::raise(1 * 60 * 60); // 1 hour for 1 course initially granted
396         raise_memory_limit(MEMORY_EXTRA);
397         $this->precheck = restore_prechecks_helper::execute_prechecks($this, $droptemptablesafter);
398         if (!array_key_exists('errors', $this->precheck)) { // No errors, can be executed
399             $this->set_status(backup::STATUS_AWAITING);
400         }
401         if (empty($this->precheck)) { // No errors nor warnings, return true
402             return true;
403         }
404         return false;
405     }
407     public function get_results() {
408         return $this->plan->get_results();
409     }
411     /**
412      * Returns true if the prechecks have been executed
413      * @return bool
414      */
415     public function precheck_executed() {
416         return (is_array($this->precheck));
417     }
419     public function get_precheck_results() {
420         if (!is_array($this->precheck)) {
421             throw new restore_controller_exception('precheck_not_executed');
422         }
423         return $this->precheck;
424     }
426     /**
427      * Save controller information
428      *
429      * @param bool $includeobj to decide if the object itself must be updated (true) or no (false)
430      * @param bool $cleanobj to decide if the object itself must be cleaned (true) or no (false)
431      */
432     public function save_controller($includeobj = true, $cleanobj = false) {
433         // Going to save controller to persistent storage, calculate checksum for later checks and save it
434         // TODO: flag the controller as NA. Any operation on it should be forbidden util loaded back
435         $this->log('saving controller to db', backup::LOG_DEBUG);
436         if ($includeobj ) {  // Only calculate checksum if we are going to include the object.
437             $this->checksum = $this->calculate_checksum();
438         }
439         restore_controller_dbops::save_controller($this, $this->checksum, $includeobj, $cleanobj);
440     }
442     public static function load_controller($restoreid) {
443         // Load controller from persistent storage
444         // TODO: flag the controller as available. Operations on it can continue
445         $controller = restore_controller_dbops::load_controller($restoreid);
446         $controller->log('loading controller from db', backup::LOG_DEBUG);
447         return $controller;
448     }
450     /**
451      * class method to provide pseudo random unique "correct" tempdir names
452      */
453     public static function get_tempdir_name($courseid = 0, $userid = 0) {
454         // Current epoch time + courseid + userid + random bits
455         return md5(time() . '-' . $courseid . '-'. $userid . '-'. random_string(20));
456     }
458     /**
459      * Converts from current format to backup::MOODLE format
460      */
461     public function convert() {
462         global $CFG;
463         require_once($CFG->dirroot . '/backup/util/helper/convert_helper.class.php');
465         // Basic/initial prevention against time/memory limits
466         core_php_time_limit::raise(1 * 60 * 60); // 1 hour for 1 course initially granted
467         raise_memory_limit(MEMORY_EXTRA);
468         $this->progress->start_progress('Backup format conversion');
470         if ($this->status != backup::STATUS_REQUIRE_CONV) {
471             throw new restore_controller_exception('cannot_convert_not_required_status');
472         }
474         $this->log('backup format conversion required', backup::LOG_INFO);
476         // Run conversion to the proper format
477         if (!convert_helper::to_moodle2_format($this->get_tempdir(), $this->format, $this->get_logger())) {
478             // todo - unable to find the conversion path, what to do now?
479             // throwing the exception as a temporary solution
480             throw new restore_controller_exception('unable_to_find_conversion_path');
481         }
483         $this->log('backup format conversion successful', backup::LOG_INFO);
485         // If no exceptions were thrown, then we are in the proper format
486         $this->format = backup::FORMAT_MOODLE;
488         // Load plan, apply security and set status based on interactivity
489         $this->load_plan();
491         // Perform all initial security checks and apply (2nd param) them to settings automatically
492         restore_check::check_security($this, true);
494         if ($this->interactive == backup::INTERACTIVE_YES) {
495             $this->set_status(backup::STATUS_SETTING_UI);
496         } else {
497             $this->set_status(backup::STATUS_NEED_PRECHECK);
498         }
499         $this->progress->end_progress();
500     }
502 // Protected API starts here
504     protected function calculate_restoreid() {
505         // Current epoch time + tempdir + courseid + interactive + mode + userid + target + operation + random bits
506         $this->restoreid = md5(time() . '-' . $this->tempdir . '-' . $this->courseid . '-'. $this->interactive . '-' .
507                                $this->mode . '-' . $this->userid . '-'. $this->target . '-' . $this->operation . '-' .
508                                random_string(20));
509     }
511     protected function load_plan() {
512         // First of all, we need to introspect the moodle_backup.xml file
513         // in order to detect all the required stuff. So, create the
514         // monster $info structure where everything will be defined
515         $this->log('loading backup info', backup::LOG_DEBUG);
516         $this->info = backup_general_helper::get_backup_information($this->tempdir);
518         // Set the controller type to the one found in the information
519         $this->type = $this->info->type;
521         // Set the controller samesite flag as needed
522         $this->samesite = backup_general_helper::backup_is_samesite($this->info);
524         // Now we load the plan that will be configured following the
525         // information provided by the $info
526         $this->log('loading controller plan', backup::LOG_DEBUG);
527         $this->plan = new restore_plan($this);
528         $this->plan->build(); // Build plan for this controller
529         $this->set_status(backup::STATUS_PLANNED);
530     }
532     /**
533      * Apply defaults from the global admin settings
534      */
535     protected function apply_defaults() {
536         $this->log('applying restore defaults', backup::LOG_DEBUG);
537         restore_controller_dbops::apply_config_defaults($this);
538         $this->set_status(backup::STATUS_CONFIGURED);
539     }
542 /*
543  * Exception class used by all the @restore_controller stuff
544  */
545 class restore_controller_exception extends backup_exception {
547     public function __construct($errorcode, $a=NULL, $debuginfo=null) {
548         parent::__construct($errorcode, $a, $debuginfo);
549     }