backup MDL-22140 Added conf settings to control the default general backup settings
[moodle.git] / backup / util / settings / base_setting.class.php
1 <?php
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/>.
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  */
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  */
35 abstract class base_setting {
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;
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';
50     // Visible/hidden
51     const VISIBLE = 1;
52     const HIDDEN  = 0;
54     // Editable/locked (by different causes)
55     const NOT_LOCKED           = 3;
56     const LOCKED_BY_CONFIG     = 5;
57     const LOCKED_BY_HIERARCHY  = 7;
58     const LOCKED_BY_PERMISSION = 9;
60     // Type of change to inform dependencies
61     const CHANGED_VALUE      = 1;
62     const CHANGED_VISIBILITY = 2;
63     const CHANGED_STATUS     = 3;
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...)
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...
72     protected $dependencies = array(); // array of dependent (observer) objects (usually setting_base ones)
73     protected $dependenton = array();
75     /**
76      * The user interface for this setting
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;
81     /**
82      * An array that contains the identifier and component of a help string if one
83      * has been set
84      * @var array
85      */
86     protected $help = array();
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         }
95         // Validate value
96         $value = $this->validate_value($vtype, $value);
98         // Check visibility
99         $visibility = $this->validate_visibility($visibility);
101         // Check status
102         $status = $this->validate_status($status);
104         $this->name        = $name;
105         $this->vtype       = $vtype;
106         $this->value       = $value;
107         $this->visibility  = $visibility;
108         $this->status      = $status;
110         // Generate a default ui
111         $this->uisetting = new base_setting_ui($this);
112     }
114     public function get_name() {
115         return $this->name;
116     }
118     public function get_value() {
119         return $this->value;
120     }
122     public function get_visibility() {
123         return $this->visibility;
124     }
126     public function get_status() {
127         return $this->status;
128     }
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');
138                 case self::LOCKED_BY_CONFIG:
139                     throw new base_setting_exception('setting_locked_by_config');
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     }
149     public function set_visibility($visibility) {
150         $visibility = $this->validate_visibility($visibility);
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         }
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     }
170     public function set_status($status) {
171         $status = $this->validate_status($status);
173         // If the setting is being unlocked first check whether an other settings
174         // this setting is dependent on are locked. If they are then we still don't
175         // want to lock this setting.
176         if (count($this->dependenton) > 0 && $status == base_setting::NOT_LOCKED) {
177             foreach ($this->dependenton as $dependency) {
178                 if ($dependency->is_locked()) {
179                     // It still needs to be locked
180                     $status = base_setting::LOCKED_BY_HIERARCHY;
181                     break;
182                 }
183             }
184         }
186         $oldstatus = $this->status;
187         $this->status = $status;
188         if ($status !== $oldstatus) { // Status has changed, let's inform dependencies
189             $this->inform_dependencies(self::CHANGED_STATUS, $oldstatus);
190         }
191     }
193     /**
194      * Gets an array of properties for all of the dependencies that will affect
195      * this setting.
196      *
197      * This method returns an array rather than the dependencies in order to
198      * minimise the memory footprint of for the potentially huge recursive
199      * dependency structure that we may be dealing with.
200      *
201      * This method also ensures that all dependencies are transmuted to affect
202      * the setting in question and that we don't provide any duplicates.
203      *
204      * @param string|null $settingname
205      * @return array
206      */
207     public function get_my_dependency_properties($settingname=null) {
208         if ($settingname ==  null) {
209             $settingname = $this->get_ui_name();
210         }
211         $dependencies = array();
212         foreach ($this->dependenton as $dependenton) {
213             $properties = $dependenton->get_moodleform_properties();
214             $properties['setting'] = $settingname;
215             $dependencies[$properties['setting'].'-'.$properties['dependenton']] = $properties;
216             $dependencies = array_merge($dependencies, $dependenton->get_setting()->get_my_dependency_properties($settingname));
217         }
218         return $dependencies;
219     }
221     /**
222      * Returns all of the dependencies that affect this setting.
223      * e.g. settings this setting depends on.
224      *
225      * @return array Array of setting_dependency's
226      */
227     public function get_settings_depended_on() {
228         return $this->dependenton;
229     }
231     /**
232      * Checks if there are other settings that are dependent on this setting
233      *
234      * @return bool True if there are other settings that are dependent on this setting
235      */
236     public function has_dependent_settings() {
237         return (count($this->dependencies)>0);
238     }
240     /**
241      * Checks if this setting is dependent on any other settings
242      *
243      * @return bool True if this setting is dependent on any other settings
244      */
245     public function has_dependencies_on_settings() {
246         return (count($this->dependenton)>0);
247     }
249     /**
250      * Sets the user interface for this setting
251      *
252      * @param base_setting_ui $ui
253      */
254     public function set_ui(backup_setting_ui $ui) {
255         $this->uisetting = $ui;
256     }
258     /**
259      * Gets the user interface for this setting
260      *
261      * @return base_setting_ui
262      */
263     public function get_ui() {
264         return $this->uisetting;
265     }
267     /**
268      * Adds a dependency where another setting depends on this setting.
269      * @param setting_dependency $dependency
270      */
271     public function register_dependency(setting_dependency $dependency) {
272         if ($this->is_circular_reference($dependency->get_dependent_setting())) {
273             $a = new stdclass();
274             $a->alreadydependent = $this->name;
275             $a->main = $dependentsetting->get_name();
276             throw new base_setting_exception('setting_circular_reference', $a);
277         }
278         $this->dependencies[$dependency->get_dependent_setting()->get_name()] = $dependency;
279         $dependency->get_dependent_setting()->register_dependent_dependency($dependency);
280     }
281     /**
282      * Adds a dependency where this setting is dependent on another.
283      *
284      * This should only be called internally once we are sure it is not cicrular.
285      *
286      * @param setting_dependency $dependency
287      */
288     protected function register_dependent_dependency(setting_dependency $dependency) {
289         $this->dependenton[$dependency->get_setting()->get_name()] = $dependency;
290     }
292     /**
293      * Quick method to add a dependency to this setting.
294      *
295      * The dependency created is done so by inspecting this setting and the
296      * setting that is passed in as the dependent setting.
297      *
298      * @param base_setting $dependentsetting
299      * @param int $type One of setting_dependency::*
300      * @param array $options
301      */
302     public function add_dependency(base_setting $dependentsetting, $type=null, $options=array()) {
303         if ($this->is_circular_reference($dependentsetting)) {
304             $a = new stdclass();
305             $a->alreadydependent = $this->name;
306             $a->main = $dependentsetting->get_name();
307             throw new base_setting_exception('setting_circular_reference', $a);
308         }
309         // Check the settings hasn't been already added
310         if (array_key_exists($dependentsetting->get_name(), $this->dependencies)) {
311             throw new base_setting_exception('setting_already_added');
312         }
314         $options = (array)$options;
316         if (!array_key_exists('defaultvalue', $options)) {
317             $options['defaultvalue'] = false;
318         }
320         if ($type == null) {
321             switch ($this->vtype) {
322                 case self::IS_BOOLEAN :
323                     if ($this->get_ui_type() == self::UI_HTML_CHECKBOX) {
324                         if ($this->value) {
325                             $type = setting_dependency::DISABLED_NOT_CHECKED;
326                         } else {
327                             $type = setting_dependency::DISABLED_CHECKED;
328                         }
329                     } else {
330                         if ($this->value) {
331                             $type = setting_dependency::DISABLED_FALSE;
332                         } else {
333                             $type = setting_dependency::DISABLED_TRUE;
334                         }
335                     }
336                     break;
337                 case self::IS_FILENAME :
338                 case self::IS_PATH :
339                 case self::IS_INTEGER :
340                 default :
341                     $type = setting_dependency::DISABLED_VALUE;
342                     break;
343             }
344         }
346         switch ($type) {
347             case setting_dependency::DISABLED_VALUE :
348                 if (!array_key_exists('value', $options)) {
349                     throw new base_setting_exception('dependency_needs_value');
350                 }
351                 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, $options['value'], $options['defaultvalue']);
352                 break;
353             case setting_dependency::DISABLED_TRUE :
354                 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, true, $options['defaultvalue']);
355                 break;
356             case setting_dependency::DISABLED_FALSE :
357                 $dependency = new setting_dependency_disabledif_equals($this, $dependentsetting, false, $options['defaultvalue']);
358                 break;
359             case setting_dependency::DISABLED_CHECKED :
360                 $dependency = new setting_dependency_disabledif_checked($this, $dependentsetting, $options['defaultvalue']);
361                 break;
362             case setting_dependency::DISABLED_NOT_CHECKED :
363                 $dependency = new setting_dependency_disabledif_not_checked($this, $dependentsetting, $options['defaultvalue']);
364                 break;
365             case setting_dependency::DISABLED_EMPTY :
366                 $dependency = new setting_dependency_disabledif_empty($this, $dependentsetting, $options['defaultvalue']);
367                 break;
368             case setting_dependency::DISABLED_NOT_EMPTY :
369                 $dependency = new setting_dependency_disabledif_not_empty($this, $dependentsetting, $options['defaultvalue']);
370                 break;
371         }
372         $this->dependencies[$dependentsetting->get_name()] = $dependency;
373         $dependency->get_dependent_setting()->register_dependent_dependency($dependency);
374     }
376 // Protected API starts here
378     protected function validate_value($vtype, $value) {
379         if (is_null($value)) { // Nulls aren't validated
380             return null;
381         }
382         $oldvalue = $value;
383         switch ($vtype) {
384             case self::IS_BOOLEAN:
385                 $value = clean_param($oldvalue, PARAM_BOOL); // Just clean
386                 break;
387             case self::IS_INTEGER:
388                 $value = clean_param($oldvalue, PARAM_INT);
389                 if ($value != $oldvalue) {
390                     throw new base_setting_exception('setting_invalid_integer', $oldvalue);
391                 }
392                 break;
393             case self::IS_FILENAME:
394                 $value = clean_param($oldvalue, PARAM_FILE);
395                 if ($value != $oldvalue) {
396                     throw new base_setting_exception('setting_invalid_filename', $oldvalue);
397                 }
398                 break;
399             case self::IS_PATH:
400                 $value = clean_param($oldvalue, PARAM_PATH);
401                 if ($value != $oldvalue) {
402                     throw new base_setting_exception('setting_invalid_path', $oldvalue);
403                 }
404                 break;
405         }
406         return $value;
407     }
409     protected function validate_visibility($visibility) {
410         if (is_null($visibility)) {
411             $visibility = self::VISIBLE;
412         }
413         if ($visibility !== self::VISIBLE && $visibility !== self::HIDDEN) {
414             throw new base_setting_exception('setting_invalid_visibility');
415         }
416         return $visibility;
417     }
419     protected function validate_status($status) {
420         if (is_null($status)) {
421             $status = self::NOT_LOCKED;
422         }
423         if ($status !== self::NOT_LOCKED && $status !== self::LOCKED_BY_CONFIG &&
424             $status !== self::LOCKED_BY_PERMISSION && $status !== self::LOCKED_BY_HIERARCHY) {
425             throw new base_setting_exception('setting_invalid_status', $status);
426         }
427         return $status;
428     }
430     protected function validate_ui_type($type) {
431         if ($type !== self::UI_HTML_CHECKBOX && $type !== self::UI_HTML_RADIOBUTTON &&
432             $type !== self::UI_HTML_DROPDOWN && $type !== self::UI_HTML_TEXTFIELD) {
433             throw new base_setting_exception('setting_invalid_ui_type');
434         }
435         return $type;
436     }
438     protected function validate_ui_label($label) {
439         if (empty($label) || $label !== clean_param($label, PARAM_ALPHAEXT)) {
440             throw new base_setting_exception('setting_invalid_ui_label');
441         }
442         return $label;
443     }
445     protected function inform_dependencies($ctype, $oldv) {
446         foreach ($this->dependencies as $dependency) {
447             $dependency->process_change($ctype, $oldv);
448         }
449     }
451     protected function is_circular_reference($obj) {
452         // Get object dependencies recursively and check (by name) if $this is already there
453         $dependencies = $obj->get_dependencies();
454         if (array_key_exists($this->name, $dependencies) || $obj == $this) {
455             return true;
456         }
457         // Recurse the dependent settings one by one
458         foreach ($dependencies as $dependency) {
459             if ($dependency->get_dependent_setting()->is_circular_reference($obj)) {
460                 return true;
461             }
462         }
463         return false;
464     }
466     public function get_dependencies() {
467         return $this->dependencies;
468     }
470     public function get_ui_name() {
471         return $this->uisetting->get_name();
472     }
474     public function get_ui_type() {
475         return $this->uisetting->get_type();
476     }
478     /**
479      * Sets a help string for this setting
480      *
481      * @param string $identifier
482      * @param string $component
483      */
484     public function set_help($identifier, $component='moodle') {
485         $this->help = array($identifier, $component);
486     }
488     /**
489      * Gets the help string params for this setting if it has been set
490      * @return array|false An array (identifier, component) or false if not set
491      */
492     public function get_help() {
493         if ($this->has_help()) {
494             return $this->help;
495         }
496         return false;
497     }
499     /**
500      * Returns true if help has been set for this setting
501      * @return cool
502      */
503     public function has_help() {
504         return (!empty($this->help));
505     }
508 /*
509  * Exception class used by all the @setting_base stuff
510  */
511 class base_setting_exception extends backup_exception {
513     public function __construct($errorcode, $a=NULL, $debuginfo=null) {
514         parent::__construct($errorcode, $a, $debuginfo);
515     }