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