659cb6547c1078b96567b4879addb56ccb4ebdd3
[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 backup implements loggable {
35     protected $tempdir;   // Directory under dataroot/temp/backup 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...)
51     protected $info;   // Information retrieved from backup contents
52     protected $plan;   // Restore execution plan
54     protected $execution;     // inmediate/delayed
55     protected $executiontime; // epoch time when we want the restore to be executed (requires cron to run)
57     protected $logger;      // Logging chain object (moodle, inline, fs, db, syslog)
59     protected $checksum; // Cache @checksumable results for lighter @is_checksum_correct() uses
61     public function __construct($tempdir, $courseid, $interactive, $mode, $userid, $target){
62         $this->tempdir = $tempdir;
63         $this->courseid = $courseid;
64         $this->interactive = $interactive;
65         $this->mode = $mode;
66         $this->userid = $userid;
67         $this->target = $target;
69         // Apply some defaults
70         $this->type = '';
71         $this->format = backup::FORMAT_UNKNOWN;
72         $this->execution = backup::EXECUTION_INMEDIATE;
73         $this->operation = backup::OPERATION_RESTORE;
74         $this->executiontime = 0;
75         $this->samesite = false;
76         $this->checksum = '';
78         // Apply current backup version and release if necessary
79         backup_controller_dbops::apply_version_and_release();
81         // Check courseid is correct
82         restore_check::check_courseid($this->courseid);
84         // Check user is correct
85         restore_check::check_user($this->userid);
87         // Calculate unique $restoreid
88         $this->calculate_restoreid();
90         // Default logger chain (based on interactive/execution)
91         $this->logger = backup_factory::get_logger_chain($this->interactive, $this->execution, $this->restoreid);
93         // Instantiate the output_controller singleton and active it if interactive and inmediate
94         $oc = output_controller::get_instance();
95         if ($this->interactive == backup::INTERACTIVE_YES && $this->execution == backup::EXECUTION_INMEDIATE) {
96             $oc->set_active(true);
97         }
99         $this->log('instantiating restore controller', backup::LOG_INFO, $this->restoreid);
101         // Set initial status
102         $this->set_status(backup::STATUS_CREATED);
104         // Calculate original restore format
105         $this->format = backup_general_helper::detect_backup_format($tempdir);
107         // If format is not moodle2, set to conversion needed
108         if ($this->format !== backup::FORMAT_MOODLE) {
109             $this->set_status(backup::STATUS_REQUIRE_CONV);
111         // Else, format is moodle2, load plan, apply security and set status based on interactivity
112         } else {
113             // Load plan
114             $this->load_plan();
116             // Perform all initial security checks and apply (2nd param) them to settings automatically
117             restore_check::check_security($this, true);
119             if ($this->interactive == backup::INTERACTIVE_YES) {
120                 $this->set_status(backup::STATUS_SETTING_UI);
121             } else {
122                 $this->set_status(backup::STATUS_NEED_PRECHECK);
123             }
124         }
125     }
127     public function finish_ui() {
128         if ($this->status != backup::STATUS_SETTING_UI) {
129             throw new backup_controller_exception('cannot_finish_ui_if_not_setting_ui');
130         }
131         $this->set_status(backup::STATUS_NEED_PRECHECK);
132     }
134     public function process_ui_event() {
136         // Perform security checks throwing exceptions (2nd param) if something is wrong
137         restore_check::check_security($this, false);
138     }
140     public function set_status($status) {
141         $this->log('setting controller status to', backup::LOG_DEBUG, $status);
142         // TODO: Check it's a correct status
143         $this->status = $status;
144         // Ensure that, once set to backup::STATUS_AWAITING | STATUS_NEED_PRECHECK, controller is stored in DB
145         if ($status == backup::STATUS_AWAITING || $status == backup::STATUS_NEED_PRECHECK) {
146             $this->save_controller();
147             $this->logger = self::load_controller($this->restoreid)->logger; // wakeup loggers
148         }
149     }
151     public function set_execution($execution, $executiontime = 0) {
152         $this->log('setting controller execution', backup::LOG_DEBUG);
153         // TODO: Check valid execution mode
154         // TODO: Check time in future
155         // TODO: Check time = 0 if inmediate
156         $this->execution = $execution;
157         $this->executiontime = $executiontime;
159         // Default logger chain (based on interactive/execution)
160         $this->logger = backup_factory::get_logger_chain($this->interactive, $this->execution, $this->restoreid);
161     }
163 // checksumable interface methods
165     public function calculate_checksum() {
166         // Reset current checksum to take it out from calculations!
167         $this->checksum = '';
168         // Init checksum
169         $tempchecksum = md5('tempdir-'    . $this->tempdir .
170                             'restoreid-'  . $this->restoreid .
171                             'courseid-'   . $this->courseid .
172                             'type-'       . $this->type .
173                             'format-'     . $this->format .
174                             'interactive-'. $this->interactive .
175                             'mode-'       . $this->mode .
176                             'userid-'     . $this->userid .
177                             'target-'     . $this->target .
178                             'samesite-'   . $this->samesite .
179                             'operation-'  . $this->operation .
180                             'status-'     . $this->status .
181                             'execution-'  . $this->execution .
182                             'plan-'       . backup_general_helper::array_checksum_recursive(array($this->plan)) .
183                             'info-'       . backup_general_helper::array_checksum_recursive(array($this->info)) .
184                             'logger-'     . backup_general_helper::array_checksum_recursive(array($this->logger)));
185         $this->log('calculating controller checksum', backup::LOG_DEBUG, $tempchecksum);
186         return $tempchecksum;
187     }
189     public function is_checksum_correct($checksum) {
190         return $this->checksum === $checksum;
191     }
193     public function get_tempdir() {
194         return $this->tempdir;
195     }
197     public function get_restoreid() {
198         return $this->restoreid;
199     }
201     public function get_type() {
202         return $this->type;
203     }
205     public function get_operation() {
206         return $this->operation;
207     }
209     public function get_courseid() {
210         return $this->courseid;
211     }
213     public function get_format() {
214         return $this->format;
215     }
217     public function get_interactive() {
218         return $this->interactive;
219     }
221     public function get_mode() {
222         return $this->mode;
223     }
225     public function get_userid() {
226         return $this->userid;
227     }
229     public function get_target() {
230         return $this->target;
231     }
233     public function is_samesite() {
234         return $this->samesite;
235     }
237     public function get_status() {
238         return $this->status;
239     }
241     public function get_execution() {
242         return $this->execution;
243     }
245     public function get_executiontime() {
246         return $this->executiontime;
247     }
249     public function get_plan() {
250         return $this->plan;
251     }
253     public function get_info() {
254         return $this->info;
255     }
257     public function get_logger() {
258         return $this->logger;
259     }
261     public function execute_plan() {
262         return $this->plan->execute();
263     }
265     public function execute_precheck() {
266         debugging ('TODO: Not applying prechecks yet, need to link them to proper restore_precheck class!', DEBUG_DEVELOPER);
267         $this->set_status(backup::STATUS_AWAITING); // TODO: Delete this once prechecks and steps are in place
268         //return $this->precheck->execute();
269         return true;
270     }
272     public function get_results() {
273         return $this->plan->get_results();
274     }
276     public function get_precheck_results() {
277         debugging ('TODO: Not applying prechecks yet, need to link them to proper restore_precheck class!', DEBUG_DEVELOPER);
278         return array();
279         //return $this->precheck->get_results();
280     }
282     public function log($message, $level, $a = null, $depth = null, $display = false) {
283         backup_helper::log($message, $level, $a, $depth, $display, $this->logger);
284     }
286     public function save_controller() {
287         // Going to save controller to persistent storage, calculate checksum for later checks and save it
288         // TODO: flag the controller as NA. Any operation on it should be forbidden util loaded back
289         $this->log('saving controller to db', backup::LOG_DEBUG);
290         $this->checksum = $this->calculate_checksum();
291         restore_controller_dbops::save_controller($this, $this->checksum);
292     }
294     public static function load_controller($restoreid) {
295         // Load controller from persistent storage
296         // TODO: flag the controller as available. Operations on it can continue
297         $controller = restore_controller_dbops::load_controller($restoreid);
298         $controller->log('loading controller from db', backup::LOG_DEBUG);
299         return $controller;
300     }
302     /**
303      * class method to provide pseudo random unique "correct" tempdir names
304      */
305     public static function get_tempdir_name($courseid = 0, $userid = 0) {
306         // Current epoch time + courseid + userid + random bits
307         return md5(time() . '-' . $courseid . '-'. $userid . '-'. random_string(20));
308     }
310     /**
311      * convert from current format to backup::MOODLE format
312      */
313     public function convert() {
314         if ($this->status != backup::STATUS_REQUIRE_CONV) {
315             throw new restore_controller_exception('cannot_convert_not_required_status');
316         }
317         if ($this->format == backup::FORMAT_UNKNOWN) {
318             throw new restore_controller_exception('cannot_convert_from_unknown_format');
319         }
320         if ($this->format == backup::FORMAT_MOODLE1) {
321             // TODO: Implement moodle1 => moodle2 conversion
322             throw new restore_controller_exception('cannot_convert_yet_from_moodle1_format');
323         }
325         // Once conversions have finished, we check again the format
326         $newformat = backup_general_helper::detect_backup_format($tempdir);
328         // If format is moodle2, load plan, apply security and set status based on interactivity
329         if ($newformat === backup::FORMAT_MOODLE) {
330             // Load plan
331             $this->load_plan();
333             // Perform all initial security checks and apply (2nd param) them to settings automatically
334             restore_check::check_security($this, true);
336             if ($this->interactive == backup::INTERACTIVE_YES) {
337                 $this->set_status(backup::STATUS_SETTING_UI);
338             } else {
339                 $this->set_status(backup::STATUS_NEED_PRECHECK);
340             }
341         } else {
342             throw new restore_controller_exception('conversion_ended_with_wrong_format', $newformat);
343         }
344     }
346 // Protected API starts here
348     protected function calculate_restoreid() {
349         // Current epoch time + tempdir + courseid + interactive + mode + userid + target + operation + random bits
350         $this->restoreid = md5(time() . '-' . $this->tempdir . '-' . $this->courseid . '-'. $this->interactive . '-' .
351                                $this->mode . '-' . $this->userid . '-'. $this->target . '-' . $this->operation . '-' .
352                                random_string(20));
353     }
355     protected function load_plan() {
356         // First of all, we need to introspect the moodle_backup.xml file
357         // in order to detect all the required stuff. So, create the
358         // monster $info structure where everything will be defined
359         $this->log('loading backup info', backup::LOG_DEBUG);
360         $this->info = backup_general_helper::get_backup_information($this->tempdir);
362         // Set the controller type to the one found in the information
363         $this->type = $this->info->type;
365         // Set the controller samesite flag as needed
366         $this->samesite = backup_general_helper::backup_is_samesite($this->info);
368         // Now we load the plan that will be configured following the
369         // information provided by the $info
370         $this->log('loading controller plan', backup::LOG_DEBUG);
371         $this->plan = new restore_plan($this);
372         $this->plan->build(); // Build plan for this controller
373         $this->set_status(backup::STATUS_PLANNED);
374     }
377 /*
378  * Exception class used by all the @restore_controller stuff
379  */
380 class restore_controller_exception extends backup_exception {
382     public function __construct($errorcode, $a=NULL, $debuginfo=null) {
383         parent::__construct($errorcode, $a, $debuginfo);
384     }