MDL-14589 Check input better, preventing notices when using an editor without draftfiles
[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
74 // Note: all the UI stuff could go to independent classes in the future...
75 protected $ui_type; // setting_base::UI_HTML_CHECKBOX/setting_base::UI_HTML_RADIOBUTTON...
76 protected $ui_label; // UI label of the setting
77 protected $ui_values; // array of value => ui value of the setting
78 protected $ui_options;// array of custom ui options
79
80 public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
81 // Check vtype
82 if ($vtype !== self::IS_BOOLEAN && $vtype !== self::IS_INTEGER &&
83 $vtype !== self::IS_FILENAME && $vtype !== self::IS_PATH) {
84 throw new base_setting_exception('setting_invalid_type');
85 }
86
87 // Validate value
88 $value = $this->validate_value($vtype, $value);
89
90 // Check visibility
91 $visibility = $this->validate_visibility($visibility);
92
93 // Check status
94 $status = $this->validate_status($status);
95
96 $this->name = $name;
97 $this->vtype = $vtype;
98 $this->value = $value;
99 $this->visibility = $visibility;
100 $this->status = $status;
101 $this->dependencies= array();
102
103 // Apply these defaults
104 $this->ui_type = self::UI_HTML_DROPDOWN;
105 $this->ui_label = $name;
106 $this->ui_values = array();
107 $this->ui_options = array();
108 }
109
110 public function get_name() {
111 return $this->name;
112 }
113
114 public function get_value() {
115 return $this->value;
116 }
117
118 public function get_visibility() {
119 return $this->visibility;
120 }
121
122 public function get_status() {
123 return $this->status;
124 }
125
126 public function set_value($value) {
127 // Validate value
128 $value = $this->validate_value($this->vtype, $value);
129 // Only can change value if setting is not locked
130 if ($this->status != self::NOT_LOCKED) {
131 switch ($this->status) {
132 case self::LOCKED_BY_PERMISSION:
133 throw new base_setting_exception('setting_locked_by_permission');
cd0034d8
EL
134 case self::LOCKED_BY_CONFIG:
135 throw new base_setting_exception('setting_locked_by_config');
69dd0c8c
EL
136 }
137 }
138 $oldvalue = $this->value;
139 $this->value = $value;
140 if ($value !== $oldvalue) { // Value has changed, let's inform dependencies
141 $this->inform_dependencies(self::CHANGED_VALUE, $oldvalue);
142 }
143 }
144
145 public function set_visibility($visibility) {
146 $visibility = $this->validate_visibility($visibility);
147 $oldvisibility = $this->visibility;
148 $this->visibility = $visibility;
149 if ($visibility !== $oldvisibility) { // Visibility has changed, let's inform dependencies
150 $this->inform_dependencies(self::CHANGED_VISIBILITY, $oldvisibility);
151 }
152 }
153
154 public function set_status($status) {
cd0034d8 155 print_object('setting '. $this->name . ' to status ' . $status);
69dd0c8c
EL
156 $status = $this->validate_status($status);
157 $oldstatus = $this->status;
158 $this->status = $status;
159 if ($status !== $oldstatus) { // Status has changed, let's inform dependencies
160 $this->inform_dependencies(self::CHANGED_STATUS, $oldstatus);
161 }
162 }
163
164 public function set_ui($type, $label, $values, $options) {
165 $type = $this->validate_ui_type($type);
166 $label =$this->validate_ui_label($label);
167 $this->ui_type = $type;
168 $this->ui_label = $label;
169 $this->set_ui_values($values);
170 $this->set_ui_options($options);
171 }
172
173 public function set_ui_values($values) {
174 $this->ui_values = $values;
175 }
176
177 public function set_ui_options($options) {
178 $this->ui_options = $options;
179 }
180
181 public function add_dependency($obj) {
182 if ($this->is_circular_reference($obj)) {
183 $a = new stdclass();
184 $a->alreadydependent = $this->name;
185 $a->main = $obj->get_name();
186 throw new base_setting_exception('setting_circular_reference', $a);
187 }
188 // Check the settings hasn't been already added
189 if (array_key_exists($obj->get_name(), $this->dependencies)) {
190 throw new base_setting_exception('setting_already_added');
191 }
192 $this->dependencies[$obj->get_name()] = $obj;
193 }
194
195// Protected API starts here
196
197 protected function validate_value($vtype, $value) {
198 if (is_null($value)) { // Nulls aren't validated
199 return null;
200 }
201 $oldvalue = $value;
202 switch ($vtype) {
203 case self::IS_BOOLEAN:
204 $value = clean_param($oldvalue, PARAM_BOOL); // Just clean
205 break;
206 case self::IS_INTEGER:
207 $value = clean_param($oldvalue, PARAM_INT);
208 if ($value != $oldvalue) {
209 throw new base_setting_exception('setting_invalid_integer', $oldvalue);
210 }
211 break;
212 case self::IS_FILENAME:
213 $value = clean_param($oldvalue, PARAM_FILE);
214 if ($value != $oldvalue) {
215 throw new base_setting_exception('setting_invalid_filename', $oldvalue);
216 }
217 break;
218 case self::IS_PATH:
219 $value = clean_param($oldvalue, PARAM_PATH);
220 if ($value != $oldvalue) {
221 throw new base_setting_exception('setting_invalid_path', $oldvalue);
222 }
223 break;
224 }
225 return $value;
226 }
227
228 protected function validate_visibility($visibility) {
229 if (is_null($visibility)) {
230 $visibility = self::VISIBLE;
231 }
232 if ($visibility !== self::VISIBLE && $visibility !== self::HIDDEN) {
233 throw new base_setting_exception('setting_invalid_visibility');
234 }
235 return $visibility;
236 }
237
238 protected function validate_status($status) {
239 if (is_null($status)) {
240 $status = self::NOT_LOCKED;
241 }
ce937f99
EL
242 if ($status !== self::NOT_LOCKED && $status !== self::LOCKED_BY_CONFIG &&
243 $status !== self::LOCKED_BY_PERMISSION && $status !== self::LOCKED_BY_HIERARCHY) {
244 throw new base_setting_exception('setting_invalid_status', $status);
69dd0c8c
EL
245 }
246 return $status;
247 }
248
249 protected function validate_ui_type($type) {
250 if ($type !== self::UI_HTML_CHECKBOX && $type !== self::UI_HTML_RADIOBUTTON &&
251 $type !== self::UI_HTML_DROPDOWN && $type !== self::UI_HTML_TEXTFIELD) {
252 throw new base_setting_exception('setting_invalid_ui_type');
253 }
254 return $type;
255 }
256
257 protected function validate_ui_label($label) {
258 if (empty($label) || $label !== clean_param($label, PARAM_ALPHAEXT)) {
259 throw new base_setting_exception('setting_invalid_ui_label');
260 }
261 return $label;
262 }
263
264 protected function inform_dependencies($ctype, $oldv) {
265 foreach ($this->dependencies as $dependency) {
266 $dependency->process_change($this, $ctype, $oldv);
267 }
268 }
269
270 protected function is_circular_reference($obj) {
271 // Get object dependencies recursively and check (by name) if $this is already there
272 $dependencies = $obj->get_dependencies();
273 if (array_key_exists($this->name, $dependencies) || $obj == $this) {
274 return true;
275 }
276 return false;
277 }
278
279 protected function get_dependencies() {
280 $dependencies = array();
281 foreach ($this->dependencies as $dependency) {
282 $dependencies[$dependency->get_name()] = $dependency->get_name();
283 $dependencies = array_merge($dependencies, $dependency->get_dependencies());
284 }
285 return $dependencies;
286 }
287
288// Implementable API starts here
289
290 abstract public function process_change($setting, $ctype, $oldv);
291}
292
293/*
294 * Exception class used by all the @setting_base stuff
295 */
296class base_setting_exception extends backup_exception {
297
298 public function __construct($errorcode, $a=NULL, $debuginfo=null) {
299 parent::__construct($errorcode, $a, $debuginfo);
300 }
301}