backup/util/settings/base_setting.class.php

   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  */
  35 abstract 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)
  55     const NOT_LOCKED           = 3;
  56     const LOCKED_BY_CONFIG     = 5;
  57     const LOCKED_BY_HIERARCHY  = 7;
  58     const LOCKED_BY_PERMISSION = 9;
  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(); // array of dependent (observer) objects (usually setting_base ones)
  73     protected $dependenton = array();
  74
  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;
  80
  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();
  87
  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;
 109
 110         // Generate a default ui
 111         $this->uisetting = new base_setting_ui($this);
 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');
 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     }
 148
 149     public function set_visibility($visibility) {
 150         $visibility = $this->validate_visibility($visibility);
 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
 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);
 172
 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         }
 185
 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     }
 192
 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     }
 220
 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     }
 230
 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     }
 239
 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     }
 248
 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     }
 257
 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     }
 266
 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     }
 291
 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         }
 313
 314         $options = (array)$options;
 315
 316         if (!array_key_exists('defaultvalue', $options)) {
 317             $options['defaultvalue'] = false;
 318         }
 319
 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         }
 345
 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     }
 375
 376 // Protected API starts here
 377
 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     }
 408
 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     }
 418
 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     }
 429
 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     }
 437
 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     }
 444
 445     protected function inform_dependencies($ctype, $oldv) {
 446         foreach ($this->dependencies as $dependency) {
 447             $dependency->process_change($ctype, $oldv);
 448         }
 449     }
 450
 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     }
 465
 466     public function get_dependencies() {
 467         return $this->dependencies;
 468     }
 469
 470     public function get_ui_name() {
 471         return $this->uisetting->get_name();
 472     }
 473
 474     public function get_ui_type() {
 475         return $this->uisetting->get_type();
 476     }
 477
 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     }
 487
 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     }
 498
 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     }
 506 }
 507
 508 /*
 509  * Exception class used by all the @setting_base stuff
 510  */
 511 class base_setting_exception extends backup_exception {
 512
 513     public function __construct($errorcode, $a=NULL, $debuginfo=null) {
 514         parent::__construct($errorcode, $a, $debuginfo);
 515     }
 516 }