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