backup MDL-26572 add new param to plugin and subplugin functions
[moodle.git] / backup / moodle2 / restore_plugin.class.php
CommitLineData
41941110
EL
1<?php
2
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/>.
17
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 */
24
25/**
26 * Class implementing the plugins support for moodle2 restore
27 *
28 * TODO: Finish phpdocs
41941110
EL
29 */
30abstract class restore_plugin {
31
32 protected $plugintype;
33 protected $pluginname;
34 protected $connectionpoint;
35 protected $step;
36 protected $task;
37
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 }
45
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 }
50
51 $paths = array();
52 $this->connectionpoint = $connectionpoint;
53 $methodname = 'define_' . basename($this->connectionpoint->get_path()) . '_plugin_structure';
54
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 }
65
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 }
82
9f68f2d5
EL
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 }
127
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 }
135
41941110
EL
136// Protected API starts here
137
138// restore_step/structure_step/task wrappers
139
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 }
146
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 }
159
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 }
166
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 }
173
174 /**
175 * Return the new id of a mapping for the given itemname
176 *
4b43b107
EL
177 * @param string $itemname the type of item
178 * @param int $oldid the item ID from the backup
179 * @param mixed $ifnotfound what to return if $oldid wasnt found. Defaults to false
41941110 180 */
4b43b107
EL
181 protected function get_mappingid($itemname, $oldid, $ifnotfound = false) {
182 return $this->step->get_mappingid($itemname, $oldid, $ifnotfound);
41941110
EL
183 }
184
185 /**
186 * Return the complete mapping from the given itemname, itemid
187 */
188 protected function get_mapping($itemname, $oldid) {
189 return $this->step->get_mapping($itemname, $oldid);
190 }
191
192 /**
193 * Add all the existing file, given their component and filearea and one backup_ids itemname to match with
194 */
195 protected function add_related_files($component, $filearea, $mappingitemname, $filesctxid = null, $olditemid = null) {
196 $this->step->add_related_files($component, $filearea, $mappingitemname, $filesctxid, $olditemid);
197 }
198
199 /**
200 * Apply course startdate offset based in original course startdate and course_offset_startdate setting
201 * Note we are using one static cache here, but *by restoreid*, so it's ok for concurrence/multiple
202 * executions in the same request
203 */
204 protected function apply_date_offset($value) {
205 return $this->step->apply_date_offset($value);
206 }
207
1e37c391
EL
208 /**
209 * Returns the value of one (task/plan) setting
210 */
211 protected function get_setting_value($name) {
212 if (is_null($this->task)) {
213 throw new restore_step_exception('not_specified_restore_task');
214 }
215 return $this->task->get_setting_value($name);
216 }
217
218// end of restore_step/structure_step/task wrappers
219
41941110
EL
220 /**
221 * Simple helper function that returns the name for the restore_path_element
222 * It's not mandatory to use it but recommended ;-)
223 */
224 protected function get_namefor($name = '') {
225 $name = $name !== '' ? '_' . $name : '';
226 return $this->plugintype . '_' . $this->pluginname . $name;
227 }
228
229 /**
230 * Simple helper function that returns the base (prefix) of the path for the restore_path_element
231 * Useful if we used get_recommended_name() in backup. It's not mandatory to use it but recommended ;-)
232 */
233 protected function get_pathfor($path = '') {
234 $path = trim($path, '/') !== '' ? '/' . trim($path, '/') : '';
235 return $this->connectionpoint->get_path() . '/' .
236 'plugin_' . $this->plugintype . '_' .
237 $this->pluginname . '_' . basename($this->connectionpoint->get_path()) . $path;
238 }
239}