MDL-53700 competency: Migrating backup logic to core
[moodle.git] / backup / moodle2 / restore_activity_task.class.php
CommitLineData
864842aa
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/**
f9dab4be
DM
19 * Defines restore_activity_task class
20 *
21 * @package core_backup
22 * @subpackage moodle2
23 * @category backup
24 * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
25 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
864842aa
EL
26 */
27
f9dab4be
DM
28defined('MOODLE_INTERNAL') || die();
29
864842aa
EL
30/**
31 * abstract activity task that provides all the properties and common tasks to be performed
32 * when one activity is being restored
33 *
34 * TODO: Finish phpdocs
35 */
36abstract class restore_activity_task extends restore_task {
37
38 protected $info; // info related to activity gathered from backup file
5ab8d2de
EL
39 protected $modulename; // name of the module
40 protected $moduleid; // new (target) id of the course module
41 protected $oldmoduleid; // old (original) id of the course module
be7b29ef 42 protected $oldmoduleversion; // old (original) version of the module
5ab8d2de
EL
43 protected $contextid; // new (target) context of the activity
44 protected $oldcontextid;// old (original) context of the activity
45 protected $activityid; // new (target) id of the activity
46 protected $oldactivityid;// old (original) id of the activity
864842aa
EL
47
48 /**
49 * Constructor - instantiates one object of this class
50 */
51 public function __construct($name, $info, $plan = null) {
864842aa 52 $this->info = $info;
5ab8d2de
EL
53 $this->modulename = $this->info->modulename;
54 $this->moduleid = 0;
55 $this->oldmoduleid = $this->info->moduleid;
be7b29ef 56 $this->oldmoduleversion = 0;
5ab8d2de
EL
57 $this->contextid = 0;
58 $this->oldcontextid = 0;
59 $this->activityid = 0;
60 $this->oldactivityid = 0;
864842aa
EL
61 parent::__construct($name, $plan);
62 }
63
64 /**
65 * Activity tasks have their own directory to read files
66 */
67 public function get_taskbasepath() {
5ab8d2de
EL
68 return $this->get_basepath() . '/' . $this->info->directory;
69 }
70
71 public function set_moduleid($moduleid) {
72 $this->moduleid = $moduleid;
73 }
74
25b4558c 75 public function set_old_moduleversion($oldmoduleversion) {
be7b29ef
TH
76 $this->oldmoduleversion = $oldmoduleversion;
77 }
78
5ab8d2de
EL
79 public function set_activityid($activityid) {
80 $this->activityid = $activityid;
81 }
82
83 public function set_old_activityid($activityid) {
84 $this->oldactivityid = $activityid;
85 }
86
87 public function set_contextid($contextid) {
88 $this->contextid = $contextid;
89 }
90
91 public function set_old_contextid($contextid) {
92 $this->oldcontextid = $contextid;
93 }
94
95 public function get_modulename() {
96 return $this->modulename;
97 }
98
99 public function get_moduleid() {
100 return $this->moduleid;
101 }
102
25b4558c 103 public function get_old_moduleversion() {
be7b29ef
TH
104 return $this->oldmoduleversion;
105 }
106
5ab8d2de
EL
107 public function get_activityid() {
108 return $this->activityid;
109 }
110
111 public function get_old_activityid() {
112 return $this->oldactivityid;
113 }
114
115 public function get_contextid() {
116 return $this->contextid;
117 }
118
119 public function get_old_contextid() {
120 return $this->oldcontextid;
864842aa
EL
121 }
122
123 /**
124 * Create all the steps that will be part of this task
125 */
126 public function build() {
127
128 // If we have decided not to restore activities, prevent anything to be built
129 if (!$this->get_setting_value('activities')) {
130 $this->built = true;
131 return;
132 }
133
5ab8d2de
EL
134 // Load he course_module estructure, generating it (with instance = 0)
135 // but allowing the creation of the target context needed in following steps
136 $this->add_step(new restore_module_structure_step('module_info', 'module.xml'));
137
138 // Here we add all the common steps for any activity and, in the point of interest
139 // we call to define_my_steps() is order to get the particular ones inserted in place.
140 $this->define_my_steps();
141
142 // Roles (optionally role assignments and always role overrides)
143 $this->add_step(new restore_ras_and_caps_structure_step('course_ras_and_caps', 'roles.xml'));
144
145 // Filters (conditionally)
146 if ($this->get_setting_value('filters')) {
147 $this->add_step(new restore_filters_structure_step('activity_filters', 'filters.xml'));
148 }
149
150 // Comments (conditionally)
151 if ($this->get_setting_value('comments')) {
152 $this->add_step(new restore_comments_structure_step('activity_comments', 'comments.xml'));
8331a159
AA
153 }
154
155 // Calendar events (conditionally)
156 if ($this->get_setting_value('calendarevents')) {
157 $this->add_step(new restore_calendarevents_structure_step('activity_calendar', 'calendar.xml'));
5ab8d2de
EL
158 }
159
9a1cfcbc
EL
160 // Grades (module-related, rest of gradebook is restored later if possible: cats, calculations...)
161 $this->add_step(new restore_activity_grades_structure_step('activity_grades', 'grades.xml'));
5ab8d2de 162
37065c2e
DM
163 // Advanced grading methods attached to the module
164 $this->add_step(new restore_activity_grading_structure_step('activity_grading', 'grading.xml'));
165
167eb033
FM
166 // Grade history. The setting 'grade_history' is handled in the step.
167 $this->add_step(new restore_activity_grade_history_structure_step('activity_grade_history', 'grade_history.xml'));
168
5095f325 169 // Userscompletion (conditionally)
5ab8d2de 170 if ($this->get_setting_value('userscompletion')) {
5095f325 171 $this->add_step(new restore_userscompletion_structure_step('activity_userscompletion', 'completion.xml'));
5ab8d2de
EL
172 }
173
0f66aced 174 // Logs (conditionally)
5ab8d2de 175 if ($this->get_setting_value('logs')) {
ea6c5643 176 // Legacy logs.
0f66aced 177 $this->add_step(new restore_activity_logs_structure_step('activity_logs', 'logs.xml'));
ea6c5643
EL
178 // New log stores.
179 $this->add_step(new restore_activity_logstores_structure_step('activity_logstores', 'logstores.xml'));
5ab8d2de 180 }
864842aa 181
8417c3a6
FM
182 // Activity competencies.
183 $this->add_step(new restore_activity_competencies_structure_step('activity_competencies', 'competencies.xml'));
184
864842aa
EL
185 // At the end, mark it as built
186 $this->built = true;
187 }
188
189 /**
190 * Exceptionally override the execute method, so, based in the activity_included setting, we are able
191 * to skip the execution of one task completely
192 */
193 public function execute() {
194
195 // Find activity_included_setting
196 if (!$this->get_setting_value('included')) {
197 $this->log('activity skipped by _included setting', backup::LOG_DEBUG, $this->name);
58328ce8 198 $this->plan->set_excluding_activities(); // Inform plan we are excluding actvities
864842aa
EL
199
200 } else { // Setting tells us it's ok to execute
201 parent::execute();
202 }
203 }
204
205
206 /**
207 * Specialisation that, first of all, looks for the setting within
208 * the task with the the prefix added and later, delegates to parent
209 * without adding anything
210 */
211 public function get_setting($name) {
212 $namewithprefix = $this->info->modulename . '_' . $this->info->moduleid . '_' . $name;
213 $result = null;
214 foreach ($this->settings as $key => $setting) {
215 if ($setting->get_name() == $namewithprefix) {
216 if ($result != null) {
217 throw new base_task_exception('multiple_settings_by_name_found', $namewithprefix);
218 } else {
219 $result = $setting;
220 }
221 }
222 }
223 if ($result) {
224 return $result;
225 } else {
226 // Fallback to parent
227 return parent::get_setting($name);
228 }
229 }
230
39aa0280
EL
231 /**
232 * Given a commment area, return the itemname that contains the itemid mappings
233 *
234 * By default both are the same (commentarea = itemname), so return it. If some
235 * module uses a different approach, this method can be overriden in its taks
236 */
237 public function get_comment_mapping_itemname($commentarea) {
238 return $commentarea;
239 }
240
5ab8d2de
EL
241 /**
242 * Define (add) particular steps that each activity can have
243 */
244 abstract protected function define_my_steps();
245
246 /**
247 * Define the contents in the activity that must be
248 * processed by the link decoder
249 */
7c109ea3
PS
250 static public function define_decode_contents() {
251 throw new coding_exception('define_decode_contents() method needs to be overridden in each subclass of restore_activity_task');
252 }
5ab8d2de
EL
253
254 /**
255 * Define the decoding rules for links belonging
256 * to the activity to be executed by the link decoder
257 */
7c109ea3
PS
258 static public function define_decode_rules() {
259 throw new coding_exception('define_decode_rules() method needs to be overridden in each subclass of restore_activity_task');
260 }
5ab8d2de 261
0f66aced
EL
262 /**
263 * Define the restore log rules that will be applied
264 * by the {@link restore_logs_processor} when restoring
265 * activity logs. It must return one array
266 * of {@link restore_log_rule} objects
267 */
268 static public function define_restore_log_rules() {
269 throw new coding_exception('define_restore_log_rules() method needs to be overridden in each subclass of restore_activity_task');
270 }
271
864842aa
EL
272// Protected API starts here
273
274 /**
275 * Define the common setting that any restore activity will have
276 */
277 protected function define_settings() {
278
279 // All the settings related to this activity will include this prefix
280 $settingprefix = $this->info->modulename . '_' . $this->info->moduleid . '_';
281
282 // All these are common settings to be shared by all activities
283
284 // Define activity_include (to decide if the whole task must be really executed)
285 // Dependent of:
286 // - activities root setting
287 // - section_included setting (if exists)
288 $settingname = $settingprefix . 'included';
289 $activity_included = new restore_activity_generic_setting($settingname, base_setting::IS_BOOLEAN, true);
d9f95015
FM
290 $activity_included->get_ui()->set_icon(new pix_icon('icon', get_string('pluginname', $this->modulename),
291 $this->modulename, array('class' => 'iconlarge icon-post')));
864842aa
EL
292 $this->add_setting($activity_included);
293 // Look for "activities" root setting
294 $activities = $this->plan->get_setting('activities');
295 $activities->add_dependency($activity_included);
296 // Look for "section_included" section setting (if exists)
297 $settingname = 'section_' . $this->info->sectionid . '_included';
298 if ($this->plan->setting_exists($settingname)) {
299 $section_included = $this->plan->get_setting($settingname);
300 $section_included->add_dependency($activity_included);
301 }
302
303 // Define activity_userinfo. Dependent of:
304 // - users root setting
305 // - section_userinfo setting (if exists)
d0565885 306 // - activity_included setting.
864842aa 307 $settingname = $settingprefix . 'userinfo';
d0565885 308 $defaultvalue = false;
5ab8d2de 309 if (isset($this->info->settings[$settingname]) && $this->info->settings[$settingname]) { // Only enabled when available
864842aa
EL
310 $defaultvalue = true;
311 }
d0565885 312
864842aa 313 $activity_userinfo = new restore_activity_userinfo_setting($settingname, base_setting::IS_BOOLEAN, $defaultvalue);
d0565885
TH
314 if (!$defaultvalue) {
315 // This is a bit hacky, but if there is no user data to restore, then
316 // we replace the standard check-box with a select menu with the
317 // single choice 'No', and the select menu is clever enough that if
318 // there is only one choice, it just displays a static string.
319 //
320 // It would probably be better design to have a special UI class
321 // setting_ui_checkbox_or_no, rather than this hack, but I am not
322 // going to do that today.
323 $activity_userinfo->set_ui(new backup_setting_ui_select($activity_userinfo, '-',
324 array(0 => get_string('no'))));
325 } else {
326 $activity_userinfo->get_ui()->set_label('-');
327 }
328
864842aa 329 $this->add_setting($activity_userinfo);
d0565885 330
864842aa
EL
331 // Look for "users" root setting
332 $users = $this->plan->get_setting('users');
333 $users->add_dependency($activity_userinfo);
d0565885 334
864842aa
EL
335 // Look for "section_userinfo" section setting (if exists)
336 $settingname = 'section_' . $this->info->sectionid . '_userinfo';
337 if ($this->plan->setting_exists($settingname)) {
338 $section_userinfo = $this->plan->get_setting($settingname);
339 $section_userinfo->add_dependency($activity_userinfo);
340 }
d0565885
TH
341
342 // Look for "activity_included" setting.
864842aa
EL
343 $activity_included->add_dependency($activity_userinfo);
344
d0565885 345 // End of common activity settings, let's add the particular ones.
864842aa
EL
346 $this->define_my_settings();
347 }
348
349 /**
350 * Define (add) particular settings that each activity can have
351 */
352 abstract protected function define_my_settings();
864842aa 353}