MDL-24962 backup - circular refs destroyer for backup plan
[moodle.git] / backup / util / settings / base_setting.class.php
CommitLineData
69dd0c8c
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-settings
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 * This abstract class defines one basic setting
27 *
28 * Each setting will be able to control its name, value (from a list), ui
29 * representation (check box, drop down, text field...), visibility, status
30 * (editable/locked...) and its hierarchy with other settings (using one
31 * like-observer pattern.
32 *
33 * TODO: Finish phpdocs
34 */
35abstract class base_setting {
36
37 // Some constants defining different ui representations for the setting
38 const UI_NONE = 0;
39 const UI_HTML_CHECKBOX = 10;
40 const UI_HTML_RADIOBUTTON = 20;
41 const UI_HTML_DROPDOWN = 30;
42 const UI_HTML_TEXTFIELD = 40;
43
44 // Type of validation to perform against the value (relaying in PARAM_XXX validations)
45 const IS_BOOLEAN = 'bool';
46 const IS_INTEGER = 'int';
47 const IS_FILENAME= 'file';
48 const IS_PATH = 'path';
785d6603 49 const IS_TEXT = 'text';
69dd0c8c
EL
50
51 // Visible/hidden
52 const VISIBLE = 1;
53 const HIDDEN = 0;
54
55 // Editable/locked (by different causes)
ce937f99
EL
56 const NOT_LOCKED = 3;
57 const LOCKED_BY_CONFIG = 5;
69dd0c8c 58 const LOCKED_BY_HIERARCHY = 7;
ce937f99 59 const LOCKED_BY_PERMISSION = 9;
69dd0c8c
EL
60
61 // Type of change to inform dependencies
62 const CHANGED_VALUE = 1;
63 const CHANGED_VISIBILITY = 2;
64 const CHANGED_STATUS = 3;
65
66 protected $name; // name of the setting
67 protected $value; // value of the setting
68 protected $vtype; // type of value (setting_base::IS_BOOLEAN/setting_base::IS_INTEGER...)
69
70 protected $visibility; // visibility of the setting (setting_base::VISIBLE/setting_base::HIDDEN)
71 protected $status; // setting_base::NOT_LOCKED/setting_base::LOCKED_BY_PERMISSION...
72
72d5e574
SH
73 protected $dependencies = array(); // array of dependent (observer) objects (usually setting_base ones)
74 protected $dependenton = array();
69dd0c8c 75
1904e9b3 76 /**
f6ae3f01 77 * The user interface for this setting
1904e9b3
SH
78 * @var backup_setting_ui|backup_setting_ui_checkbox|backup_setting_ui_radio|backup_setting_ui_select|backup_setting_ui_text
79 */
80 protected $uisetting;
81
1a83fcb5 82 /**
f6ae3f01
SH
83 * An array that contains the identifier and component of a help string if one
84 * has been set
1a83fcb5
SH
85 * @var array
86 */
87 protected $help = array();
88
69dd0c8c
EL
89 public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
90 // Check vtype
91 if ($vtype !== self::IS_BOOLEAN && $vtype !== self::IS_INTEGER &&
785d6603
SH
92 $vtype !== self::IS_FILENAME && $vtype !== self::IS_PATH &&
93 $vtype !== self::IS_TEXT) {
69dd0c8c
EL
94 throw new base_setting_exception('setting_invalid_type');
95 }
96
97 // Validate value
98 $value = $this->validate_value($vtype, $value);
99
100 // Check visibility
101 $visibility = $this->validate_visibility($visibility);
102
103 // Check status
104 $status = $this->validate_status($status);
105
106 $this->name = $name;
107 $this->vtype = $vtype;
108 $this->value = $value;
109 $this->visibility = $visibility;
110 $this->status = $status;
69dd0c8c 111
1904e9b3 112 // Generate a default ui
17f04f53 113 $this->uisetting = new base_setting_ui($this);
69dd0c8c
EL
114 }
115
116 public function get_name() {
117 return $this->name;
118 }
119
120 public function get_value() {
121 return $this->value;
122 }
123
124 public function get_visibility() {
125 return $this->visibility;
126 }
127
128 public function get_status() {
129 return $this->status;
130 }
131
132 public function set_value($value) {
133 // Validate value
134 $value = $this->validate_value($this->vtype, $value);
135 // Only can change value if setting is not locked
136 if ($this->status != self::NOT_LOCKED) {
137 switch ($this->status) {
138 case self::LOCKED_BY_PERMISSION:
139 throw new base_setting_exception('setting_locked_by_permission');
cd0034d8
EL
140 case self::LOCKED_BY_CONFIG:
141 throw new base_setting_exception('setting_locked_by_config');
69dd0c8c
EL
142 }
143 }
144 $oldvalue = $this->value;
145 $this->value = $value;
146 if ($value !== $oldvalue) { // Value has changed, let's inform dependencies
147 $this->inform_dependencies(self::CHANGED_VALUE, $oldvalue);
148 }
149 }
150
151 public function set_visibility($visibility) {
152 $visibility = $this->validate_visibility($visibility);
72d5e574
SH
153
154 // If this setting is dependent on other settings first check that all
155 // of those settings are visible
156 if (count($this->dependenton) > 0 && $visibility == base_setting::VISIBLE) {
157 foreach ($this->dependenton as $dependency) {
158 if ($dependency->get_setting()->get_visibility() != base_setting::VISIBLE) {
159 $visibility = base_setting::HIDDEN;
160 break;
161 }
162 }
163 }
164
69dd0c8c
EL
165 $oldvisibility = $this->visibility;
166 $this->visibility = $visibility;
167 if ($visibility !== $oldvisibility) { // Visibility has changed, let's inform dependencies
168 $this->inform_dependencies(self::CHANGED_VISIBILITY, $oldvisibility);
169 }
170 }
171
172 public function set_status($status) {
173 $status = $this->validate_status($status);
72d5e574 174
61ebef8f
SH
175 // If the setting is being unlocked first check whether an other settings
176 // this setting is dependent on are locked. If they are then we still don't
177 // want to lock this setting.
72d5e574
SH
178 if (count($this->dependenton) > 0 && $status == base_setting::NOT_LOCKED) {
179 foreach ($this->dependenton as $dependency) {
61ebef8f
SH
180 if ($dependency->is_locked()) {
181 // It still needs to be locked
72d5e574
SH
182 $status = base_setting::LOCKED_BY_HIERARCHY;
183 break;
184 }
185 }
186 }
187
69dd0c8c
EL
188 $oldstatus = $this->status;
189 $this->status = $status;
190 if ($status !== $oldstatus) { // Status has changed, let's inform dependencies
191 $this->inform_dependencies(self::CHANGED_STATUS, $oldstatus);
192 }
193 }
194
6ed9a7da
SH
195 /**
196 * Gets an array of properties for all of the dependencies that will affect
197 * this setting.
198 *
61ebef8f 199 * This method returns an array rather than the dependencies in order to
6ed9a7da
SH
200 * minimise the memory footprint of for the potentially huge recursive
201 * dependency structure that we may be dealing with.
202 *
203 * This method also ensures that all dependencies are transmuted to affect
204 * the setting in question and that we don't provide any duplicates.
205 *
206 * @param string|null $settingname
207 * @return array
208 */
209 public function get_my_dependency_properties($settingname=null) {
210 if ($settingname == null) {
211 $settingname = $this->get_ui_name();
212 }
213 $dependencies = array();
214 foreach ($this->dependenton as $dependenton) {
215 $properties = $dependenton->get_moodleform_properties();
216 $properties['setting'] = $settingname;
217 $dependencies[$properties['setting'].'-'.$properties['dependenton']] = $properties;
218 $dependencies = array_merge($dependencies, $dependenton->get_setting()->get_my_dependency_properties($settingname));
219 }
220 return $dependencies;
221 }
222
61ebef8f
SH
223 /**
224 * Returns all of the dependencies that affect this setting.
225 * e.g. settings this setting depends on.
226 *
227 * @return array Array of setting_dependency's
228 */
229 public function get_settings_depended_on() {
230 return $this->dependenton;
231 }
232
e43ba980
SH
233 /**
234 * Checks if there are other settings that are dependent on this setting
235 *
236 * @return bool True if there are other settings that are dependent on this setting
237 */
238 public function has_dependent_settings() {
239 return (count($this->dependencies)>0);
240 }
241
242 /**
243 * Checks if this setting is dependent on any other settings
244 *
245 * @return bool True if this setting is dependent on any other settings
246 */
247 public function has_dependencies_on_settings() {
248 return (count($this->dependenton)>0);
249 }
250
251 /**
252 * Sets the user interface for this setting
253 *
17f04f53 254 * @param base_setting_ui $ui
e43ba980 255 */
1904e9b3
SH
256 public function set_ui(backup_setting_ui $ui) {
257 $this->uisetting = $ui;
69dd0c8c
EL
258 }
259
e43ba980
SH
260 /**
261 * Gets the user interface for this setting
262 *
17f04f53 263 * @return base_setting_ui
e43ba980 264 */
1904e9b3
SH
265 public function get_ui() {
266 return $this->uisetting;
69dd0c8c
EL
267 }
268
72d5e574
SH
269 /**
270 * Adds a dependency where another setting depends on this setting.
271 * @param setting_dependency $dependency
272 */
273 public function register_dependency(setting_dependency $dependency) {
e35fb479 274 if ($this->is_circular_reference($dependency->get_dependent_setting())) {
72d5e574
SH
275 $a = new stdclass();
276 $a->alreadydependent = $this->name;
277 $a->main = $dependentsetting->get_name();
278 throw new base_setting_exception('setting_circular_reference', $a);
279 }
e35fb479
SH
280 $this->dependencies[$dependency->get_dependent_setting()->get_name()] = $dependency;
281 $dependency->get_dependent_setting()->register_dependent_dependency($dependency);
72d5e574
SH
282 }
283 /**
284 * Adds a dependency where this setting is dependent on another.
285 *
286 * This should only be called internally once we are sure it is not cicrular.
287 *
288 * @param setting_dependency $dependency
289 */
290 protected function register_dependent_dependency(setting_dependency $dependency) {
291 $this->dependenton[$dependency->get_setting()->get_name()] = $dependency;
292 }
293
e43ba980
SH
294 /**
295 * Quick method to add a dependency to this setting.
296 *
297 * The dependency created is done so by inspecting this setting and the
298 * setting that is passed in as the dependent setting.
299 *
300 * @param base_setting $dependentsetting
301 * @param int $type One of setting_dependency::*
302 * @param array $options
303 */
1904e9b3
SH
304 public function add_dependency(base_setting $dependentsetting, $type=null, $options=array()) {
305 if ($this->is_circular_reference($dependentsetting)) {
69dd0c8c
EL
306 $a = new stdclass();
307 $a->alreadydependent = $this->name;
1904e9b3 308 $a->main = $dependentsetting->get_name();
69dd0c8c
EL
309 throw new base_setting_exception('setting_circular_reference', $a);
310 }
311 // Check the settings hasn't been already added
1904e9b3 312 if (array_key_exists($dependentsetting->get_name(), $this->dependencies)) {
69dd0c8c
EL
313 throw new base_setting_exception('setting_already_added');
314 }
1904e9b3
SH
315
316 $options = (array)$options;
317
318 if (!array_key_exists('defaultvalue', $options)) {
319 $options['defaultvalue'] = false;
320 }
321
322 if ($type == null) {
323 switch ($this->vtype) {
324 case self::IS_BOOLEAN :
84e546e0
SH
325 if ($this->get_ui_type() == self::UI_HTML_CHECKBOX) {
326 if ($this->value) {
327 $type = setting_dependency::DISABLED_NOT_CHECKED;
328 } else {
329 $type = setting_dependency::DISABLED_CHECKED;
330 }
1904e9b3 331 } else {
84e546e0
SH
332 if ($this->value) {
333 $type = setting_dependency::DISABLED_FALSE;
334 } else {
335 $type = setting_dependency::DISABLED_TRUE;
336 }
1904e9b3
SH
337 }
338 break;
339 case self::IS_FILENAME :
340 case self::IS_PATH :
341 case self::IS_INTEGER :
342 default :
343 $type = setting_dependency::DISABLED_VALUE;
344 break;
345 }
346 }
347
348 switch ($type) {
349 case setting_dependency::DISABLED_VALUE :
350 if (!array_key_exists('value', $options)) {
351 throw new base_setting_exception('dependency_needs_value');
352 }
353 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, $options['value'], $options['defaultvalue']);
354 break;
355 case setting_dependency::DISABLED_TRUE :
1904e9b3
SH
356 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, true, $options['defaultvalue']);
357 break;
358 case setting_dependency::DISABLED_FALSE :
1904e9b3
SH
359 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, false, $options['defaultvalue']);
360 break;
84e546e0
SH
361 case setting_dependency::DISABLED_CHECKED :
362 $dependency = new setting_dependency_disabledif_checked($this, $dependentsetting, $options['defaultvalue']);
363 break;
364 case setting_dependency::DISABLED_NOT_CHECKED :
365 $dependency = new setting_dependency_disabledif_not_checked($this, $dependentsetting, $options['defaultvalue']);
366 break;
17f04f53
SH
367 case setting_dependency::DISABLED_EMPTY :
368 $dependency = new setting_dependency_disabledif_empty($this, $dependentsetting, $options['defaultvalue']);
369 break;
370 case setting_dependency::DISABLED_NOT_EMPTY :
371 $dependency = new setting_dependency_disabledif_not_empty($this, $dependentsetting, $options['defaultvalue']);
372 break;
1904e9b3
SH
373 }
374 $this->dependencies[$dependentsetting->get_name()] = $dependency;
e35fb479 375 $dependency->get_dependent_setting()->register_dependent_dependency($dependency);
69dd0c8c
EL
376 }
377
378// Protected API starts here
379
380 protected function validate_value($vtype, $value) {
381 if (is_null($value)) { // Nulls aren't validated
382 return null;
383 }
384 $oldvalue = $value;
385 switch ($vtype) {
386 case self::IS_BOOLEAN:
387 $value = clean_param($oldvalue, PARAM_BOOL); // Just clean
388 break;
389 case self::IS_INTEGER:
390 $value = clean_param($oldvalue, PARAM_INT);
391 if ($value != $oldvalue) {
392 throw new base_setting_exception('setting_invalid_integer', $oldvalue);
393 }
394 break;
395 case self::IS_FILENAME:
396 $value = clean_param($oldvalue, PARAM_FILE);
397 if ($value != $oldvalue) {
398 throw new base_setting_exception('setting_invalid_filename', $oldvalue);
399 }
400 break;
401 case self::IS_PATH:
402 $value = clean_param($oldvalue, PARAM_PATH);
403 if ($value != $oldvalue) {
404 throw new base_setting_exception('setting_invalid_path', $oldvalue);
405 }
406 break;
785d6603
SH
407 case self::IS_TEXT:
408 $value = clean_param($oldvalue, PARAM_TEXT);
409 if ($value != $oldvalue) {
410 throw new base_setting_exception('setting_invalid_text', $oldvalue);
411 }
412 break;
69dd0c8c
EL
413 }
414 return $value;
415 }
416
417 protected function validate_visibility($visibility) {
418 if (is_null($visibility)) {
419 $visibility = self::VISIBLE;
420 }
421 if ($visibility !== self::VISIBLE && $visibility !== self::HIDDEN) {
422 throw new base_setting_exception('setting_invalid_visibility');
423 }
424 return $visibility;
425 }
426
427 protected function validate_status($status) {
428 if (is_null($status)) {
429 $status = self::NOT_LOCKED;
430 }
ce937f99
EL
431 if ($status !== self::NOT_LOCKED && $status !== self::LOCKED_BY_CONFIG &&
432 $status !== self::LOCKED_BY_PERMISSION && $status !== self::LOCKED_BY_HIERARCHY) {
433 throw new base_setting_exception('setting_invalid_status', $status);
69dd0c8c
EL
434 }
435 return $status;
436 }
437
69dd0c8c
EL
438 protected function inform_dependencies($ctype, $oldv) {
439 foreach ($this->dependencies as $dependency) {
1904e9b3 440 $dependency->process_change($ctype, $oldv);
69dd0c8c
EL
441 }
442 }
443
444 protected function is_circular_reference($obj) {
445 // Get object dependencies recursively and check (by name) if $this is already there
446 $dependencies = $obj->get_dependencies();
447 if (array_key_exists($this->name, $dependencies) || $obj == $this) {
448 return true;
449 }
17f04f53
SH
450 // Recurse the dependent settings one by one
451 foreach ($dependencies as $dependency) {
452 if ($dependency->get_dependent_setting()->is_circular_reference($obj)) {
453 return true;
454 }
455 }
69dd0c8c
EL
456 return false;
457 }
458
84e546e0
SH
459 public function get_dependencies() {
460 return $this->dependencies;
461 }
462
463 public function get_ui_name() {
464 return $this->uisetting->get_name();
465 }
466
467 public function get_ui_type() {
468 return $this->uisetting->get_type();
69dd0c8c
EL
469 }
470
1a83fcb5
SH
471 /**
472 * Sets a help string for this setting
473 *
474 * @param string $identifier
475 * @param string $component
476 */
477 public function set_help($identifier, $component='moodle') {
478 $this->help = array($identifier, $component);
479 }
480
481 /**
482 * Gets the help string params for this setting if it has been set
483 * @return array|false An array (identifier, component) or false if not set
484 */
485 public function get_help() {
486 if ($this->has_help()) {
487 return $this->help;
488 }
489 return false;
490 }
491
492 /**
493 * Returns true if help has been set for this setting
494 * @return cool
495 */
496 public function has_help() {
497 return (!empty($this->help));
498 }
69dd0c8c
EL
499}
500
501/*
502 * Exception class used by all the @setting_base stuff
503 */
504class base_setting_exception extends backup_exception {
505
506 public function __construct($errorcode, $a=NULL, $debuginfo=null) {
507 parent::__construct($errorcode, $a, $debuginfo);
508 }
509}