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