e15612030e4357bcb6f10087989b6e8ac7b02dc7
[moodle.git] / backup / util / ui / base_ui.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  * This file contains the backup user interface class
20  *
21  * @package   moodlecore
22  * @copyright 2010 Sam Hemelryk
23  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 /**
27  * This is the backup user interface class
28  *
29  * The backup user interface class manages the user interface and backup for
30  * Moodle.
31  *
32  * @copyright 2010 Sam Hemelryk
33  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
34  */
35 abstract class base_ui {
36     /**
37      * The progress of this instance of the backup ui class
38      */
39     const PROGRESS_INTIAL = 0;
40     const PROGRESS_PROCESSED = 1;
41     const PROGRESS_SAVED = 2;
42     const PROGRESS_EXECUTED = 3;
43     /**
44      * The controller
45      * @var backup_controller|restore_controller
46      */
47     protected $controller;
48     /**
49      * The current stage
50      * @var base_ui_stage
51      */
52     protected $stage;
53     /**
54      * The current progress of the UI
55      * @var int One of self::PROGRESS_*
56      */
57     protected $progress;
58     /**
59      * The number of changes made by dependency enforcement
60      * @var int
61      */
62     protected $dependencychanges = 0;
64     /**
65      * Yay for constructors
66      * @param backup_controller $controller
67      */
68     public function __construct($controller, array $params=null) {
69         $this->controller = $controller;
70         $this->progress = self::PROGRESS_INTIAL;
71         $this->stage = $this->initialise_stage(null, $params);
72         // Process UI event before to be safe
73         $this->controller->process_ui_event();
74     }
75     /**
76      * Destorys the backup controller and the loaded stage.
77      */
78     public function destroy() {
80         if ($this->controller) {
81             $this->controller->destroy();
82         }
83         unset($this->stage);
85     }
86     /**
87      * Intialises what ever stage is requested. If none are requested we check
88      * params for 'stage' and default to initial
89      *
90      * @param int|null $stage The desired stage to intialise or null for the default
91      * @return base_ui_stage
92      */
93     abstract protected function initialise_stage($stage = null, array $params=null);
94     /**
95      * This processes the current stage of the backup
96      * @return bool
97      */
98     public function process() {
99         if ($this->progress >= self::PROGRESS_PROCESSED) {
100             throw new backup_ui_exception('backupuialreadyprocessed');
101         }
102         $this->progress = self::PROGRESS_PROCESSED;
104         if (optional_param('previous', false, PARAM_BOOL) && $this->stage->get_stage() > $this->get_first_stage_id()) {
105             $this->stage = $this->initialise_stage($this->stage->get_prev_stage(), $this->stage->get_params());
106             return false;
107         }
109         // Process the stage
110         $processoutcome = $this->stage->process();
112         if ($processoutcome !== false) {
113             $this->stage = $this->initialise_stage($this->stage->get_next_stage(), $this->stage->get_params());
114         }
116         // Process UI event after to check changes are valid
117         $this->controller->process_ui_event();
118         return $processoutcome;
119     }
120     /**
121      * Saves the backup controller.
122      *
123      * Once this has been called nothing else can be changed in the controller.
124      *
125      * @return bool
126      */
127     public function save_controller() {
128         if ($this->progress >= self::PROGRESS_SAVED) {
129             throw new base_ui_exception('backupuialreadysaved');
130         }
131         $this->progress = self::PROGRESS_SAVED;
132         // First enforce dependencies
133         $this->enforce_dependencies();
134         // Process UI event after to check any changes are valid
135         $this->controller->process_ui_event();
136         // Save the controller
137         $this->controller->save_controller();
138         return true;
139     }
140     /**
141      * Displays the UI for the backup!
142      *
143      * Note: The UI makes use of mforms (ewww!) thus it will automatically print
144      * out the result rather than returning a string of HTML like other parts of Moodle
145      *
146      * @return bool
147      */
148     public function display() {
149         if ($this->progress < self::PROGRESS_SAVED) {
150             throw new base_ui_exception('backupsavebeforedisplay');
151         }
152         $this->stage->display();
153     }
154     /**
155      * Gets all backup tasks from the controller
156      * @return array Array of backup_task
157      */
158     public function get_tasks() {
159         $plan = $this->controller->get_plan();
160         $tasks = $plan->get_tasks();
161         return $tasks;
162     }
163     /**
164      * Gets the stage we are on
165      * @return int
166      */
167     public function get_stage() {
168         return $this->stage->get_stage();
169     }
170     /**
171      * Gets the name of the stage we are on
172      * @return string
173      */
174     public function get_stage_name() {
175         return $this->stage->get_name();
176     }
177     /**
178      * Gets the backup id from the controller
179      * @return string
180      */
181     abstract public function get_uniqueid();
182     /**
183      * Executes the backup plan
184      * @return bool
185      */
186     abstract public function execute();
187     /**
188      * Enforces dependencies on all settings. Call before save
189      * @return bool True if dependencies were enforced and changes were made
190      */
191     protected function enforce_dependencies() {
192         // Get the plan
193         $plan = $this->controller->get_plan();
194         // Get the tasks as a var so we can iterate by reference
195         $tasks = $plan->get_tasks();
196         $changes = 0;
197         foreach ($tasks as &$task) {
198             // Store as a var so we can iterate by reference
199             $settings = $task->get_settings();
200             foreach ($settings as &$setting) {
201                 // Get all dependencies for iteration by reference
202                 $dependencies = $setting->get_dependencies();
203                 foreach ($dependencies as &$dependency) {
204                     // Enforce each dependency
205                     if ($dependency->enforce()) {
206                         $changes++;
207                     }
208                 }
209             }
210         }
211         // Store the number of settings that changed through enforcement
212         $this->dependencychanges = $changes;
213         return ($changes>0);
214     }
215     /**
216      * Returns true if enforce_dependencies changed any settings
217      * @return bool
218      */
219     public function enforce_changed_dependencies() {
220         return ($this->dependencychanges > 0);
221     }
222     /**
223      * Loads the backup controller if we are tracking one
224      * @return backup_controller|false
225      */
226     public static function load_controller($uniqueid=false) {
227         throw new coding_exception('load_controller() method needs to be overridden in each subclass of base_ui');
228     }
229     /**
230      * Gets an array of progress bar items that can be displayed through the backup renderer.
231      * @return array Array of items for the progress bar
232      */
233     abstract public function get_progress_bar();
234     /**
235      * Gets the format for the backup
236      * @return int
237      */
238     public function get_format() {
239         return $this->controller->get_format();
240     }
241     /**
242      * Gets the type of the backup
243      * @return int
244      */
245     public function get_type() {
246         return $this->controller->get_type();
247     }
248     public function get_controller() {
249         return $this->controller;
250     }
251     /**
252      * Gets the ID used in creating the controller. Relates to course/section/cm
253      * @return int
254      */
255     public function get_controller_id() {
256         return $this->controller->get_id();
257     }
258     /**
259      * Gets the requested setting
260      * @param string $name
261      * @return mixed
262      */
263     public function get_setting($name, $default = false) {
264         try {
265             return $this->controller->get_plan()->get_setting($name);
266         } catch (Exception $e) {
267             debugging('Failed to find the setting: '.$name, DEBUG_DEVELOPER);
268             return $default;
269         }
270     }
271     /**
272      * Gets the value for the requested setting
273      *
274      * @param string $name
275      * @return mixed
276      */
277     public function get_setting_value($name, $default = false) {
278         try {
279             return $this->controller->get_plan()->get_setting($name)->get_value();
280         } catch (Exception $e) {
281             debugging('Failed to find the setting: '.$name, DEBUG_DEVELOPER);
282             return $default;
283         }
284     }
286     abstract public function get_name();
288     abstract public function get_first_stage_id();
291 /**
292  * Backup user interface exception. Modelled off the backup_exception class
293  */
294 class base_ui_exception extends backup_exception {}