MDL-21432 backup - clean temps after execution
[moodle.git] / backup / controller / backup_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 backup process
27  *
28  * This final class is in charge of controlling all the backup architecture, for any
29  * type of backup. Based in type, format, interactivity and target, it stores the
30  * whole execution plan and settings that will be used later by the @backup_worker,
31  * applies all the defaults, performs all the security contraints and is in charge
32  * of handling the ui if necessary. Also logging strategy is defined here.
33  *
34  * Note the class is 100% neutral and usable for *any* backup. It just stores/requests
35  * all the needed information from other backup classes in order to have everything well
36  * structured in order to allow the @backup_worker classes to do their job.
37  *
38  * In other words, a mammoth class, but don't worry, practically everything is delegated/
39  * aggregated!)
40  *
41  * TODO: Finish phpdocs
42  */
43 class backup_controller extends backup implements loggable {
45     protected $backupid; // Unique identificator for this backup
47     protected $type;   // Type of backup (activity, section, course)
48     protected $id;     // Course/section/course_module id to backup
49     protected $courseid; // courseid where the id belongs to
50     protected $format; // Format of backup (moodle, imscc)
51     protected $interactive; // yes/no
52     protected $mode;   // Purpose of the backup (default settings)
53     protected $userid; // user id executing the backup
55     protected $status; // Current status of the controller (created, planned, configured...)
57     protected $plan;   // Backup execution plan
59     protected $execution;     // inmediate/delayed
60     protected $executiontime; // epoch time when we want the backup to be executed (requires cron to run)
62     protected $destination; // Destination chain object (fs_moodle, fs_os, db, email...)
63     protected $logger;      // Logging chain object (moodle, inline, fs, db, syslog)
65     protected $checksum; // Cache @checksumable results for lighter @is_checksum_correct() uses
67     public function __construct($type, $id, $format, $interactive, $mode, $userid){
68         $this->type = $type;
69         $this->id   = $id;
70         $this->courseid = backup_controller_dbops::get_courseid_from_type_id($this->type, $this->id);
71         $this->format = $format;
72         $this->interactive = $interactive;
73         $this->mode = $mode;
74         $this->userid = $userid;
76         // Apply some defaults
77         $this->execution = backup::EXECUTION_INMEDIATE;
78         $this->executiontime = 0;
79         $this->checksum = '';
81         // Apply current backup version and release if necessary
82         backup_controller_dbops::apply_version_and_release();
84         // Check format and type are correct
85         backup_check::check_format_and_type($this->format, $this->type);
87         // Check id is correct
88         backup_check::check_id($this->type, $this->id);
90         // Check user is correct
91         backup_check::check_user($this->userid);
93         // Calculate unique $backupid
94         $this->calculate_backupid();
96         // Default logger chain (based on interactive/execution)
97         $this->logger = backup_factory::get_logger_chain($this->interactive, $this->execution, $this->backupid);
99         // Instantiate the output_controller singleton and active it if interactive and inmediate
100         $oc = output_controller::get_instance();
101         if ($this->interactive == backup::INTERACTIVE_YES && $this->execution == backup::EXECUTION_INMEDIATE) {
102             $oc->set_active(true);
103         }
105         $this->log('instantiating backup controller', backup::LOG_INFO, $this->backupid);
107         // Default destination chain (based on type/mode/execution)
108         $this->destination = backup_factory::get_destination_chain($this->type, $this->id, $this->mode, $this->execution);
110         // Set initial status
111         $this->set_status(backup::STATUS_CREATED);
113         // Load plan (based on type/format)
114         $this->load_plan();
116         // Apply all default settings (based on type/format/mode)
117         $this->apply_defaults();
119         // Perform all initial security checks and apply (2nd param) them to settings automatically
120         backup_check::check_security($this, true);
122         // Set status based on interactivity
123         if ($this->interactive == backup::INTERACTIVE_YES) {
124             $this->set_status(backup::STATUS_SETTING_UI);
125         } else {
126             $this->set_status(backup::STATUS_AWAITING);
127         }
128     }
130     public function show_ui() {
131     }
133     public function process_ui() {
134     }
136     public function finish_ui() {
137         if ($this->status != backup::STATUS_SETTING_UI) {
138             throw new backup_controller_exception('cannot_finish_ui_if_not_setting_ui');
139         }
140         $this->set_status(backup::STATUS_AWAITING);
141     }
143     public function process_ui_event() {
145         // Perform security checks throwing exceptions (2nd param) if something is wrong
146         backup_check::check_security($this, false);
147     }
149     public function set_status($status) {
150         $this->log('setting controller status to', backup::LOG_DEBUG, $status);
151         // TODO: Check it's a correct status
152         $this->status = $status;
153         // Ensure that, once set to backup::STATUS_AWAITING, controller is stored in DB
154         if ($status == backup::STATUS_AWAITING) {
155             $this->save_controller();
156             $this->logger = self::load_controller($this->backupid)->logger; // wakeup loggers
157         }
158     }
160     public function set_execution($execution, $executiontime = 0) {
161         $this->log('setting controller execution', backup::LOG_DEBUG);
162         // TODO: Check valid execution mode
163         // TODO: Check time in future
164         // TODO: Check time = 0 if inmediate
165         $this->execution = $execution;
166         $this->executiontime = $executiontime;
168         // Default destination chain (based on type/mode/execution)
169         $this->destination = backup_factory::get_destination_chain($this->type, $this->id, $this->mode, $this->execution);
171         // Default logger chain (based on interactive/execution)
172         $this->logger = backup_factory::get_logger_chain($this->interactive, $this->execution, $this->backupid);
173     }
175 // checksumable interface methods
177     public function calculate_checksum() {
178         // Reset current checksum to take it out from calculations!
179         $this->checksum = '';
180         // Init checksum
181         $tempchecksum = md5('backupid-'   . $this->backupid .
182                             'type-'       . $this->type .
183                             'id-'         . $this->id .
184                             'format-'     . $this->format .
185                             'interactive-'. $this->interactive .
186                             'mode-'       . $this->mode .
187                             'userid-'     . $this->userid .
188                             'status-'     . $this->status .
189                             'execution-'  . $this->execution .
190                             'plan-'       . backup_general_helper::array_checksum_recursive(array($this->plan)) .
191                             'destination-'. backup_general_helper::array_checksum_recursive(array($this->destination)) .
192                             'logger-'     . backup_general_helper::array_checksum_recursive(array($this->logger)));
193         $this->log('calculating controller checksum', backup::LOG_DEBUG, $tempchecksum);
194         return $tempchecksum;
195     }
197     public function is_checksum_correct($checksum) {
198         return $this->checksum === $checksum;
199     }
201     public function get_backupid() {
202         return $this->backupid;
203     }
205     public function get_type() {
206         return $this->type;
207     }
209     public function get_id() {
210         return $this->id;
211     }
213     public function get_courseid() {
214         return $this->courseid;
215     }
217     public function get_format() {
218         return $this->format;
219     }
221     public function get_interactive() {
222         return $this->interactive;
223     }
225     public function get_mode() {
226         return $this->mode;
227     }
229     public function get_userid() {
230         return $this->userid;
231     }
233     public function get_status() {
234         return $this->status;
235     }
237     public function get_execution() {
238         return $this->execution;
239     }
241     public function get_executiontime() {
242         return $this->executiontime;
243     }
245     public function get_plan() {
246         return $this->plan;
247     }
249     public function get_logger() {
250         return $this->logger;
251     }
253     public function execute_plan() {
254         return $this->plan->execute();
255     }
257     public function get_results() {
258         return $this->plan->get_results();
259     }
261     public function log($message, $level, $a = null, $depth = null, $display = false) {
262         backup_helper::log($message, $level, $a, $depth, $display, $this->logger);
263     }
266 // Protected API starts here
268     protected function calculate_backupid() {
269         // Current epoch time + type + id + format + interactive + mode + userid
270         // should be unique enough. Add one random part at the end
271         $this->backupid = md5(time() . '-' . $this->type . '-' . $this->id . '-' . $this->format . '-' .
272                               $this->interactive . '-' . $this->mode . '-' . $this->userid . '-' .
273                               random_string(20));
274     }
276     public function save_controller() {
277         // Going to save controller to persistent storage, calculate checksum for later checks and save it
278         // TODO: flag the controller as NA. Any operation on it should be forbidden util loaded back
279         $this->log('saving controller to db', backup::LOG_DEBUG);
280         $this->checksum = $this->calculate_checksum();
281         backup_controller_dbops::save_controller($this, $this->checksum);
282     }
284     public static function load_controller($backupid) {
285         // Load controller from persistent storage
286         // TODO: flag the controller as available. Operations on it can continue
287         $controller = backup_controller_dbops::load_controller($backupid);
288         $controller->log('loading controller from db', backup::LOG_DEBUG);
289         return $controller;
290     }
292     protected function load_plan() {
293         $this->log('loading controller plan', backup::LOG_DEBUG);
294         $this->plan = new backup_plan($this);
295         $this->plan->build(); // Build plan for this controller
296         $this->set_status(backup::STATUS_PLANNED);
297     }
299     protected function apply_defaults() {
300         $this->log('applying plan defaults', backup::LOG_DEBUG);
301         $this->set_status(backup::STATUS_CONFIGURED);
302     }
305 /*
306  * Exception class used by all the @backup_controller stuff
307  */
308 class backup_controller_exception extends backup_exception {
310     public function __construct($errorcode, $a=NULL, $debuginfo=null) {
311         parent::__construct($errorcode, $a, $debuginfo);
312     }