MDL-21432 backup - restore controller
[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
48     protected $status; // Current status of the controller (created, planned, configured...)
50     protected $info;   // Information retrieved from backup contents
51     protected $plan;   // Restore execution plan
53     protected $execution;     // inmediate/delayed
54     protected $executiontime; // epoch time when we want the restore to be executed (requires cron to run)
56     protected $logger;      // Logging chain object (moodle, inline, fs, db, syslog)
58     protected $checksum; // Cache @checksumable results for lighter @is_checksum_correct() uses
60     public function __construct($tempdir, $courseid, $interactive, $mode, $userid, $target){
61         $this->tempdir = $tempdir;
62         $this->courseid = $courseid;
63         $this->interactive = $interactive;
64         $this->mode = $mode;
65         $this->userid = $userid;
66         $this->target = $target;
68         // Apply some defaults
69         $this->type = '';
70         $this->format = backup::FORMAT_UNKNOWN;
71         $this->execution = backup::EXECUTION_INMEDIATE;
72         $this->operation = backup::OPERATION_RESTORE;
73         $this->executiontime = 0;
74         $this->checksum = '';
76         // Apply current backup version and release if necessary
77         backup_controller_dbops::apply_version_and_release();
79         // Check courseid is correct
80         restore_check::check_courseid($this->courseid);
82         // Check user is correct
83         restore_check::check_user($this->userid);
85         // Calculate unique $restoreid
86         $this->calculate_restoreid();
88         // Default logger chain (based on interactive/execution)
89         $this->logger = backup_factory::get_logger_chain($this->interactive, $this->execution, $this->restoreid);
91         // Instantiate the output_controller singleton and active it if interactive and inmediate
92         $oc = output_controller::get_instance();
93         if ($this->interactive == backup::INTERACTIVE_YES && $this->execution == backup::EXECUTION_INMEDIATE) {
94             $oc->set_active(true);
95         }
97         $this->log('instantiating restore controller', backup::LOG_INFO, $this->restoreid);
99         // Set initial status
100         $this->set_status(backup::STATUS_CREATED);
102         // Calculate original restore format
103         $this->format = backup_general_helper::detect_backup_format($tempdir);
105         // If format is not moodle2, set to conversion needed
106         if ($this->format !== backup::FORMAT_MOODLE) {
107             $this->set_status(backup::STATUS_REQUIRE_CONV);
109         // Else, format is moodle2, load plan, apply security and set status based on interactivity
110         } else {
111             // Load plan
112             $this->load_plan();
114             // Perform all initial security checks and apply (2nd param) them to settings automatically
115             restore_check::check_security($this, true);
117             if ($this->interactive == backup::INTERACTIVE_YES) {
118                 $this->set_status(backup::STATUS_SETTING_UI);
119             } else {
120                 $this->set_status(backup::STATUS_NEED_PRECHECK);
121             }
122         }
123     }
125     public function finish_ui() {
126         if ($this->status != backup::STATUS_SETTING_UI) {
127             throw new backup_controller_exception('cannot_finish_ui_if_not_setting_ui');
128         }
129         $this->set_status(backup::STATUS_NEED_PRECHECK);
130     }
132     public function process_ui_event() {
134         // Perform security checks throwing exceptions (2nd param) if something is wrong
135         restore_check::check_security($this, false);
136     }
138     public function set_status($status) {
139         $this->log('setting controller status to', backup::LOG_DEBUG, $status);
140         // TODO: Check it's a correct status
141         $this->status = $status;
142         // Ensure that, once set to backup::STATUS_AWAITING | STATUS_NEED_PRECHECK, controller is stored in DB
143         if ($status == backup::STATUS_AWAITING || $status == backup::STATUS_NEED_PRECHECK) {
144             $this->save_controller();
145             $this->logger = self::load_controller($this->restoreid)->logger; // wakeup loggers
146         }
147     }
149     public function set_execution($execution, $executiontime = 0) {
150         $this->log('setting controller execution', backup::LOG_DEBUG);
151         // TODO: Check valid execution mode
152         // TODO: Check time in future
153         // TODO: Check time = 0 if inmediate
154         $this->execution = $execution;
155         $this->executiontime = $executiontime;
157         // Default logger chain (based on interactive/execution)
158         $this->logger = backup_factory::get_logger_chain($this->interactive, $this->execution, $this->restoreid);
159     }
161 // checksumable interface methods
163     public function calculate_checksum() {
164         // Reset current checksum to take it out from calculations!
165         $this->checksum = '';
166         // Init checksum
167         $tempchecksum = md5('tempdir-'    . $this->tempdir .
168                             'restoreid-'  . $this->restoreid .
169                             'courseid-'   . $this->courseid .
170                             'type-'       . $this->type .
171                             'format-'     . $this->format .
172                             'interactive-'. $this->interactive .
173                             'mode-'       . $this->mode .
174                             'userid-'     . $this->userid .
175                             'target-'     . $this->target .
176                             'operation-'  . $this->operation .
177                             'status-'     . $this->status .
178                             'execution-'  . $this->execution .
179                             'plan-'       . backup_general_helper::array_checksum_recursive(array($this->plan)) .
180                             'info-'       . backup_general_helper::array_checksum_recursive(array($this->info)) .
181                             'logger-'     . backup_general_helper::array_checksum_recursive(array($this->logger)));
182         $this->log('calculating controller checksum', backup::LOG_DEBUG, $tempchecksum);
183         return $tempchecksum;
184     }
186     public function is_checksum_correct($checksum) {
187         return $this->checksum === $checksum;
188     }
190     public function get_tempdir() {
191         return $this->tempdir;
192     }
194     public function get_restoreid() {
195         return $this->restoreid;
196     }
198     public function get_type() {
199         return $this->type;
200     }
202     public function get_operation() {
203         return $this->operation;
204     }
206     public function get_courseid() {
207         return $this->courseid;
208     }
210     public function get_format() {
211         return $this->format;
212     }
214     public function get_interactive() {
215         return $this->interactive;
216     }
218     public function get_mode() {
219         return $this->mode;
220     }
222     public function get_userid() {
223         return $this->userid;
224     }
226     public function get_target() {
227         return $this->target;
228     }
230     public function get_status() {
231         return $this->status;
232     }
234     public function get_execution() {
235         return $this->execution;
236     }
238     public function get_executiontime() {
239         return $this->executiontime;
240     }
242     public function get_plan() {
243         return $this->plan;
244     }
246     public function get_info() {
247         return $this->info;
248     }
250     public function get_logger() {
251         return $this->logger;
252     }
254     public function execute_plan() {
255         return $this->plan->execute();
256     }
258     public function execute_precheck() {
259         debugging ('TODO: Not applying prechecks yet, need to link them to proper restore_precheck class!', DEBUG_DEVELOPER);
260         $this->set_status(backup::STATUS_AWAITING); // TODO: Delete this once prechecks and steps are in place
261         //return $this->precheck->execute();
262         return true;
263     }
265     public function get_results() {
266         return $this->plan->get_results();
267     }
269     public function get_precheck_results() {
270         debugging ('TODO: Not applying prechecks yet, need to link them to proper restore_precheck class!', DEBUG_DEVELOPER);
271         return array();
272         //return $this->precheck->get_results();
273     }
275     public function log($message, $level, $a = null, $depth = null, $display = false) {
276         backup_helper::log($message, $level, $a, $depth, $display, $this->logger);
277     }
279     public function save_controller() {
280         // Going to save controller to persistent storage, calculate checksum for later checks and save it
281         // TODO: flag the controller as NA. Any operation on it should be forbidden util loaded back
282         $this->log('saving controller to db', backup::LOG_DEBUG);
283         $this->checksum = $this->calculate_checksum();
284         restore_controller_dbops::save_controller($this, $this->checksum);
285     }
287     public static function load_controller($restoreid) {
288         // Load controller from persistent storage
289         // TODO: flag the controller as available. Operations on it can continue
290         $controller = restore_controller_dbops::load_controller($restoreid);
291         $controller->log('loading controller from db', backup::LOG_DEBUG);
292         return $controller;
293     }
295     /**
296      * class method to provide pseudo random unique "correct" tempdir names
297      */
298     public static function get_tempdir_name($courseid = 0, $userid = 0) {
299         // Current epoch time + courseid + userid + random bits
300         return md5(time() . '-' . $courseid . '-'. $userid . '-'. random_string(20));
301     }
303     /**
304      * convert from current format to backup::MOODLE format
305      */
306     public function convert() {
307         if ($this->status != backup::STATUS_REQUIRE_CONV) {
308             throw new restore_controller_exception('cannot_convert_not_required_status');
309         }
310         if ($this->format == backup::FORMAT_UNKNOWN) {
311             throw new restore_controller_exception('cannot_convert_from_unknown_format');
312         }
313         if ($this->format == backup::FORMAT_MOODLE1) {
314             // TODO: Implement moodle1 => moodle2 conversion
315             throw new restore_controller_exception('cannot_convert_yet_from_moodle1_format');
316         }
318         // Once conversions have finished, we check again the format
319         $newformat = backup_general_helper::detect_backup_format($tempdir);
321         // If format is moodle2, load plan, apply security and set status based on interactivity
322         if ($newformat === backup::FORMAT_MOODLE) {
323             // Load plan
324             $this->load_plan();
326             // Perform all initial security checks and apply (2nd param) them to settings automatically
327             restore_check::check_security($this, true);
329             if ($this->interactive == backup::INTERACTIVE_YES) {
330                 $this->set_status(backup::STATUS_SETTING_UI);
331             } else {
332                 $this->set_status(backup::STATUS_NEED_PRECHECK);
333             }
334         } else {
335             throw new restore_controller_exception('conversion_ended_with_wrong_format', $newformat);
336         }
337     }
339 // Protected API starts here
341     protected function calculate_restoreid() {
342         // Current epoch time + tempdir + courseid + interactive + mode + userid + target + operation + random bits
343         $this->restoreid = md5(time() . '-' . $this->tempdir . '-' . $this->courseid . '-'. $this->interactive . '-' .
344                                $this->mode . '-' . $this->userid . '-'. $this->target . '-' . $this->operation . '-' .
345                                random_string(20));
346     }
348     protected function load_plan() {
349         // First of all, we need to introspect the moodle_backup.xml file
350         // in order to detect all the required stuff. So, create the
351         // monster $info structure where everything will be defined
352         $this->log('loading backup info', backup::LOG_DEBUG);
353         $this->info = backup_general_helper::get_backup_information($this->tempdir);
355         // Set the controller type to the one found in the information
356         $this->type = $this->info->type;
358         // Now we load the plan that will be configured following the
359         // information provided by the $info
360         $this->log('loading controller plan', backup::LOG_DEBUG);
361         $this->plan = new restore_plan($this);
362         $this->plan->build(); // Build plan for this controller
363         $this->set_status(backup::STATUS_PLANNED);
364     }
367 /*
368  * Exception class used by all the @restore_controller stuff
369  */
370 class restore_controller_exception extends backup_exception {
372     public function __construct($errorcode, $a=NULL, $debuginfo=null) {
373         parent::__construct($errorcode, $a, $debuginfo);
374     }