NOBUG: Clean already implemented TODO
[moodle.git] / backup / moodle2 / restore_plugin.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-moodle2
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 plugins support for moodle2 restore
27  *
28  * TODO: Finish phpdocs
29  */
30 abstract class restore_plugin {
32     protected $plugintype;
33     protected $pluginname;
34     protected $connectionpoint;
35     protected $step;
36     protected $task;
38     public function __construct($plugintype, $pluginname, $step) {
39         $this->plugintype = $plugintype;
40         $this->pluginname = $pluginname;
41         $this->step          = $step;
42         $this->task          = $step->get_task();
43         $this->connectionpoint = '';
44     }
46     public function define_plugin_structure($connectionpoint) {
47         if (!$connectionpoint instanceof restore_path_element) {
48             throw new restore_step_exception('restore_path_element_required', $connectionpoint);
49         }
51         $paths = array();
52         $this->connectionpoint = $connectionpoint;
53         $methodname = 'define_' . basename($this->connectionpoint->get_path()) . '_plugin_structure';
55         if (method_exists($this, $methodname)) {
56             if ($bluginpaths = $this->$methodname()) {
57                 foreach ($bluginpaths as $path) {
58                     $path->set_processing_object($this);
59                     $paths[] = $path;
60                 }
61             }
62         }
63         return $paths;
64     }
66     /**
67      * after_execute dispatcher for any restore_plugin class
68      *
69      * This method will dispatch execution to the corresponding
70      * after_execute_xxx() method when available, with xxx
71      * being the connection point of the instance, so plugin
72      * classes with multiple connection points will support
73      * multiple after_execute methods, one for each connection point
74      */
75     public function launch_after_execute_methods() {
76         // Check if the after_execute method exists and launch it
77         $afterexecute = 'after_execute_' . basename($this->connectionpoint->get_path());
78         if (method_exists($this, $afterexecute)) {
79             $this->$afterexecute();
80         }
81     }
83     /**
84      * Returns one array with all the decode contents
85      * to be processed by the links decoder
86      *
87      * This method, given one plugin type, returns one
88      * array of {@link restore_decode_content} objects
89      * that will be added to the restore decoder in order
90      * to perform modifications under the plugin contents.
91      *
92      * The objects are retrieved by calling to the {@link define_decode_contents}
93      * method (when available), first in the main restore_xxxx_plugin class
94      * and later on each of the available subclasses
95      */
96     static public function get_restore_decode_contents($plugintype) {
97         $decodecontents = array();
98         // Check the requested plugintype is a valid one
99         if (!array_key_exists($plugintype, get_plugin_types($plugintype))) {
100              throw new backup_step_exception('incorrect_plugin_type', $plugintype);
101         }
102         // Check the base plugin class exists
103         $classname = 'restore_' . $plugintype . '_plugin';
104         if (!class_exists($classname)) {
105              throw new backup_step_exception('plugin_class_not_found', $classname);
106         }
107         // First, call to the define_plugin_decode_contents in the base plugin class
108         // (must exist by design in all the plugin base classes)
109         if (method_exists($classname, 'define_plugin_decode_contents')) {
110             $decodecontents = array_merge($decodecontents, call_user_func(array($classname, 'define_plugin_decode_contents')));
111         }
112         // Now, iterate over all the possible plugins available
113         // (only the needed ones have been loaded, so they will
114         // be the ones being asked here). Fetch their restore contents
115         // by calling (if exists) to their define_decode_contents() method
116         $plugins = get_plugin_list($plugintype);
117         foreach ($plugins as $plugin => $plugindir) {
118             $classname = 'restore_' . $plugintype . '_' . $plugin . '_plugin';
119             if (class_exists($classname)) {
120                 if (method_exists($classname, 'define_decode_contents')) {
121                     $decodecontents = array_merge($decodecontents, call_user_func(array($classname, 'define_decode_contents')));
122                 }
123             }
124         }
125         return $decodecontents;
126     }
128     /**
129      * Define the contents in the plugin that must be
130      * processed by the link decoder
131      */
132     static public function define_plugin_decode_contents() {
133         throw new coding_exception('define_plugin_decode_contents() method needs to be overridden in each subclass of restore_plugin');
134     }
136 // Protected API starts here
138 // restore_step/structure_step/task wrappers
140     protected function get_restoreid() {
141         if (is_null($this->task)) {
142             throw new restore_step_exception('not_specified_restore_task');
143         }
144         return $this->task->get_restoreid();
145     }
147     /**
148      * To send ids pairs to backup_ids_table and to store them into paths
149      *
150      * This method will send the given itemname and old/new ids to the
151      * backup_ids_temp table, and, at the same time, will save the new id
152      * into the corresponding restore_path_element for easier access
153      * by children. Also will inject the known old context id for the task
154      * in case it's going to be used for restoring files later
155      */
156     protected function set_mapping($itemname, $oldid, $newid, $restorefiles = false, $filesctxid = null, $parentid = null) {
157         $this->step->set_mapping($itemname, $oldid, $newid, $restorefiles, $filesctxid, $parentid);
158     }
160     /**
161      * Returns the latest (parent) old id mapped by one pathelement
162      */
163     protected function get_old_parentid($itemname) {
164         return $this->step->get_old_parentid($itemname);
165     }
167     /**
168      * Returns the latest (parent) new id mapped by one pathelement
169      */
170     protected function get_new_parentid($itemname) {
171         return $this->step->get_new_parentid($itemname);
172     }
174     /**
175      * Return the new id of a mapping for the given itemname
176      *
177      */
178     protected function get_mappingid($itemname, $oldid) {
179         return $this->step->get_mappingid($itemname, $oldid);
180     }
182     /**
183      * Return the complete mapping from the given itemname, itemid
184      */
185     protected function get_mapping($itemname, $oldid) {
186         return $this->step->get_mapping($itemname, $oldid);
187     }
189     /**
190      * Add all the existing file, given their component and filearea and one backup_ids itemname to match with
191      */
192     protected function add_related_files($component, $filearea, $mappingitemname, $filesctxid = null, $olditemid = null) {
193         $this->step->add_related_files($component, $filearea, $mappingitemname, $filesctxid, $olditemid);
194     }
196     /**
197      * Apply course startdate offset based in original course startdate and course_offset_startdate setting
198      * Note we are using one static cache here, but *by restoreid*, so it's ok for concurrence/multiple
199      * executions in the same request
200      */
201     protected function apply_date_offset($value) {
202         return $this->step->apply_date_offset($value);
203     }
205     /**
206      * Simple helper function that returns the name for the restore_path_element
207      * It's not mandatory to use it but recommended ;-)
208      */
209     protected function get_namefor($name = '') {
210         $name = $name !== '' ? '_' . $name : '';
211         return $this->plugintype . '_' . $this->pluginname . $name;
212     }
214     /**
215      * Simple helper function that returns the base (prefix) of the path for the restore_path_element
216      * Useful if we used get_recommended_name() in backup. It's not mandatory to use it but recommended ;-)
217      */
218     protected function get_pathfor($path = '') {
219         $path = trim($path, '/') !== '' ? '/' . trim($path, '/') : '';
220         return $this->connectionpoint->get_path() . '/' .
221                'plugin_' . $this->plugintype . '_' .
222                $this->pluginname . '_' . basename($this->connectionpoint->get_path()) . $path;
223     }