"fixed filemanager parameters"
[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
72 protected $dependencies; // array of dependent (observer) objects (usually setting_base ones)
73
1904e9b3 74 /**
f6ae3f01 75 * The user interface for this setting
1904e9b3
SH
76 * @var backup_setting_ui|backup_setting_ui_checkbox|backup_setting_ui_radio|backup_setting_ui_select|backup_setting_ui_text
77 */
78 protected $uisetting;
79
1a83fcb5 80 /**
f6ae3f01
SH
81 * An array that contains the identifier and component of a help string if one
82 * has been set
1a83fcb5
SH
83 * @var array
84 */
85 protected $help = array();
86
69dd0c8c
EL
87 public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
88 // Check vtype
89 if ($vtype !== self::IS_BOOLEAN && $vtype !== self::IS_INTEGER &&
90 $vtype !== self::IS_FILENAME && $vtype !== self::IS_PATH) {
91 throw new base_setting_exception('setting_invalid_type');
92 }
93
94 // Validate value
95 $value = $this->validate_value($vtype, $value);
96
97 // Check visibility
98 $visibility = $this->validate_visibility($visibility);
99
100 // Check status
101 $status = $this->validate_status($status);
102
103 $this->name = $name;
104 $this->vtype = $vtype;
105 $this->value = $value;
106 $this->visibility = $visibility;
107 $this->status = $status;
108 $this->dependencies= array();
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);
151 $oldvisibility = $this->visibility;
152 $this->visibility = $visibility;
153 if ($visibility !== $oldvisibility) { // Visibility has changed, let's inform dependencies
154 $this->inform_dependencies(self::CHANGED_VISIBILITY, $oldvisibility);
155 }
156 }
157
158 public function set_status($status) {
159 $status = $this->validate_status($status);
160 $oldstatus = $this->status;
161 $this->status = $status;
162 if ($status !== $oldstatus) { // Status has changed, let's inform dependencies
163 $this->inform_dependencies(self::CHANGED_STATUS, $oldstatus);
164 }
165 }
166
1904e9b3
SH
167 public function set_ui(backup_setting_ui $ui) {
168 $this->uisetting = $ui;
69dd0c8c
EL
169 }
170
1904e9b3
SH
171 public function make_ui($type, $label, array $attributes = null, array $options = null) {
172 $type = $this->validate_ui_type($type);
173 $label = $this->validate_ui_label($label);
174 $this->uisetting = backup_setting_ui::make($this, $type, $label, $attributes, $options);
175 if (is_array($options) || is_object($options)) {
176 $options = (array)$options;
177 switch (get_class($this->uisetting)) {
178 case 'backup_setting_ui_radio' :
179 // text
180 if (array_key_exists('text', $options)) {
181 $this->uisetting->set_text($options['text']);
182 }
183 case 'backup_setting_ui_checkbox' :
184 // value
185 if (array_key_exists('value', $options)) {
186 $this->uisetting->set_value($options['value']);
187 }
188 break;
189 case 'backup_setting_ui_select' :
190 // options
191 if (array_key_exists('options', $options)) {
192 $this->uisetting->set_values($options['options']);
193 }
194 break;
195 }
196 }
69dd0c8c
EL
197 }
198
1904e9b3
SH
199 public function get_ui() {
200 return $this->uisetting;
69dd0c8c
EL
201 }
202
1904e9b3
SH
203 public function add_dependency(base_setting $dependentsetting, $type=null, $options=array()) {
204 if ($this->is_circular_reference($dependentsetting)) {
69dd0c8c
EL
205 $a = new stdclass();
206 $a->alreadydependent = $this->name;
1904e9b3 207 $a->main = $dependentsetting->get_name();
69dd0c8c
EL
208 throw new base_setting_exception('setting_circular_reference', $a);
209 }
210 // Check the settings hasn't been already added
1904e9b3 211 if (array_key_exists($dependentsetting->get_name(), $this->dependencies)) {
69dd0c8c
EL
212 throw new base_setting_exception('setting_already_added');
213 }
1904e9b3
SH
214
215 $options = (array)$options;
216
217 if (!array_key_exists('defaultvalue', $options)) {
218 $options['defaultvalue'] = false;
219 }
220
221 if ($type == null) {
222 switch ($this->vtype) {
223 case self::IS_BOOLEAN :
224 if ($this->value) {
225 $type = setting_dependency::DISABLED_FALSE;
226 } else {
227 $type = setting_dependency::DISABLED_TRUE;
228 }
229 break;
230 case self::IS_FILENAME :
231 case self::IS_PATH :
232 case self::IS_INTEGER :
233 default :
234 $type = setting_dependency::DISABLED_VALUE;
235 break;
236 }
237 }
238
239 switch ($type) {
240 case setting_dependency::DISABLED_VALUE :
241 if (!array_key_exists('value', $options)) {
242 throw new base_setting_exception('dependency_needs_value');
243 }
244 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, $options['value'], $options['defaultvalue']);
245 break;
246 case setting_dependency::DISABLED_TRUE :
247 case setting_dependency::DISABLED_CHECKED :
248 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, true, $options['defaultvalue']);
249 break;
250 case setting_dependency::DISABLED_FALSE :
251 case setting_dependency::DISABLED_NOT_CHECKED :
252 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, false, $options['defaultvalue']);
253 break;
254 }
255 $this->dependencies[$dependentsetting->get_name()] = $dependency;
69dd0c8c
EL
256 }
257
258// Protected API starts here
259
260 protected function validate_value($vtype, $value) {
261 if (is_null($value)) { // Nulls aren't validated
262 return null;
263 }
264 $oldvalue = $value;
265 switch ($vtype) {
266 case self::IS_BOOLEAN:
267 $value = clean_param($oldvalue, PARAM_BOOL); // Just clean
268 break;
269 case self::IS_INTEGER:
270 $value = clean_param($oldvalue, PARAM_INT);
271 if ($value != $oldvalue) {
272 throw new base_setting_exception('setting_invalid_integer', $oldvalue);
273 }
274 break;
275 case self::IS_FILENAME:
276 $value = clean_param($oldvalue, PARAM_FILE);
277 if ($value != $oldvalue) {
278 throw new base_setting_exception('setting_invalid_filename', $oldvalue);
279 }
280 break;
281 case self::IS_PATH:
282 $value = clean_param($oldvalue, PARAM_PATH);
283 if ($value != $oldvalue) {
284 throw new base_setting_exception('setting_invalid_path', $oldvalue);
285 }
286 break;
287 }
288 return $value;
289 }
290
291 protected function validate_visibility($visibility) {
292 if (is_null($visibility)) {
293 $visibility = self::VISIBLE;
294 }
295 if ($visibility !== self::VISIBLE && $visibility !== self::HIDDEN) {
296 throw new base_setting_exception('setting_invalid_visibility');
297 }
298 return $visibility;
299 }
300
301 protected function validate_status($status) {
302 if (is_null($status)) {
303 $status = self::NOT_LOCKED;
304 }
ce937f99
EL
305 if ($status !== self::NOT_LOCKED && $status !== self::LOCKED_BY_CONFIG &&
306 $status !== self::LOCKED_BY_PERMISSION && $status !== self::LOCKED_BY_HIERARCHY) {
307 throw new base_setting_exception('setting_invalid_status', $status);
69dd0c8c
EL
308 }
309 return $status;
310 }
311
312 protected function validate_ui_type($type) {
313 if ($type !== self::UI_HTML_CHECKBOX && $type !== self::UI_HTML_RADIOBUTTON &&
314 $type !== self::UI_HTML_DROPDOWN && $type !== self::UI_HTML_TEXTFIELD) {
315 throw new base_setting_exception('setting_invalid_ui_type');
316 }
317 return $type;
318 }
319
320 protected function validate_ui_label($label) {
321 if (empty($label) || $label !== clean_param($label, PARAM_ALPHAEXT)) {
322 throw new base_setting_exception('setting_invalid_ui_label');
323 }
324 return $label;
325 }
326
327 protected function inform_dependencies($ctype, $oldv) {
328 foreach ($this->dependencies as $dependency) {
1904e9b3 329 $dependency->process_change($ctype, $oldv);
69dd0c8c
EL
330 }
331 }
332
333 protected function is_circular_reference($obj) {
334 // Get object dependencies recursively and check (by name) if $this is already there
335 $dependencies = $obj->get_dependencies();
336 if (array_key_exists($this->name, $dependencies) || $obj == $this) {
337 return true;
338 }
339 return false;
340 }
341
342 protected function get_dependencies() {
343 $dependencies = array();
344 foreach ($this->dependencies as $dependency) {
1904e9b3 345 $dependencies[$dependency->get_dependant_setting()->get_name()] = $dependency->get_dependant_setting();
69dd0c8c
EL
346 $dependencies = array_merge($dependencies, $dependency->get_dependencies());
347 }
348 return $dependencies;
349 }
350
1a83fcb5
SH
351 /**
352 * Sets a help string for this setting
353 *
354 * @param string $identifier
355 * @param string $component
356 */
357 public function set_help($identifier, $component='moodle') {
358 $this->help = array($identifier, $component);
359 }
360
361 /**
362 * Gets the help string params for this setting if it has been set
363 * @return array|false An array (identifier, component) or false if not set
364 */
365 public function get_help() {
366 if ($this->has_help()) {
367 return $this->help;
368 }
369 return false;
370 }
371
372 /**
373 * Returns true if help has been set for this setting
374 * @return cool
375 */
376 public function has_help() {
377 return (!empty($this->help));
378 }
69dd0c8c
EL
379}
380
381/*
382 * Exception class used by all the @setting_base stuff
383 */
384class base_setting_exception extends backup_exception {
385
386 public function __construct($errorcode, $a=NULL, $debuginfo=null) {
387 parent::__construct($errorcode, $a, $debuginfo);
388 }
389}