[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace dokuwiki\plugin\config\core\Setting;
   4  
   5  use dokuwiki\plugin\config\core\Configuration;
   6  
   7  /**
   8   * Class Setting
   9   */
  10  class Setting {
  11      /** @var string unique identifier of this setting */
  12      protected $key = '';
  13  
  14      /** @var mixed the default value of this setting */
  15      protected $default = null;
  16      /** @var mixed the local value of this setting */
  17      protected $local = null;
  18      /** @var mixed the protected value of this setting */
  19      protected $protected = null;
  20  
  21      /** @var array valid alerts, images matching the alerts are in the plugin's images directory */
  22      static protected $validCautions = array('warning', 'danger', 'security');
  23  
  24      protected $pattern = '';
  25      protected $error = false;            // only used by those classes which error check
  26      protected $input = null;             // only used by those classes which error check
  27      protected $caution = null;           // used by any setting to provide an alert along with the setting
  28  
  29      /**
  30       * Constructor.
  31       *
  32       * The given parameters will be set up as class properties
  33       *
  34       * @see initialize() to set the actual value of the setting
  35       *
  36       * @param string $key
  37       * @param array|null $params array with metadata of setting
  38       */
  39      public function __construct($key, $params = null) {
  40          $this->key = $key;
  41  
  42          if(is_array($params)) {
  43              foreach($params as $property => $value) {
  44                  $property = trim($property, '_'); // we don't use underscores anymore
  45                  $this->$property = $value;
  46              }
  47          }
  48      }
  49  
  50      /**
  51       * Set the current values for the setting $key
  52       *
  53       * This is used to initialize the setting with the data read form the config files.
  54       *
  55       * @see update() to set a new value
  56       * @param mixed $default default setting value
  57       * @param mixed $local local setting value
  58       * @param mixed $protected protected setting value
  59       */
  60      public function initialize($default = null, $local = null, $protected = null) {
  61          $this->default = $this->cleanValue($default);
  62          $this->local = $this->cleanValue($local);
  63          $this->protected = $this->cleanValue($protected);
  64      }
  65  
  66      /**
  67       * update changed setting with validated user provided value $input
  68       * - if changed value fails validation check, save it to $this->input (to allow echoing later)
  69       * - if changed value passes validation check, set $this->local to the new value
  70       *
  71       * @param  mixed $input the new value
  72       * @return boolean          true if changed, false otherwise
  73       */
  74      public function update($input) {
  75          if(is_null($input)) return false;
  76          if($this->isProtected()) return false;
  77          $input = $this->cleanValue($input);
  78  
  79          $value = is_null($this->local) ? $this->default : $this->local;
  80          if($value == $input) return false;
  81  
  82          // validate new value
  83          if($this->pattern && !preg_match($this->pattern, $input)) {
  84              $this->error = true;
  85              $this->input = $input;
  86              return false;
  87          }
  88  
  89          // update local copy of this setting with new value
  90          $this->local = $input;
  91  
  92          // setting ready for update
  93          return true;
  94      }
  95  
  96      /**
  97       * Clean a value read from a config before using it internally
  98       *
  99       * Default implementation returns $value as is. Subclasses can override.
 100       * Note: null should always be returned as null!
 101       *
 102       * This is applied in initialize() and update()
 103       *
 104       * @param mixed $value
 105       * @return mixed
 106       */
 107      protected function cleanValue($value) {
 108          return $value;
 109      }
 110  
 111      /**
 112       * Should this type of config have a default?
 113       *
 114       * @return bool
 115       */
 116      public function shouldHaveDefault() {
 117          return true;
 118      }
 119  
 120      /**
 121       * Get this setting's unique key
 122       *
 123       * @return string
 124       */
 125      public function getKey() {
 126          return $this->key;
 127      }
 128  
 129      /**
 130       * Get the key of this setting marked up human readable
 131       *
 132       * @param bool $url link to dokuwiki.org manual?
 133       * @return string
 134       */
 135      public function getPrettyKey($url = true) {
 136          $out = str_replace(Configuration::KEYMARKER, "»", $this->key);
 137          if($url && !strstr($out, '»')) {//provide no urls for plugins, etc.
 138              if($out == 'start') {
 139                  // exception, because this config name is clashing with our actual start page
 140                  return '<a href="https://www.dokuwiki.org/config:startpage">' . $out . '</a>';
 141              } else {
 142                  return '<a href="https://www.dokuwiki.org/config:' . $out . '">' . $out . '</a>';
 143              }
 144          }
 145          return $out;
 146      }
 147  
 148      /**
 149       * Returns setting key as an array key separator
 150       *
 151       * This is used to create form output
 152       *
 153       * @return string key
 154       */
 155      public function getArrayKey() {
 156          return str_replace(Configuration::KEYMARKER, "']['", $this->key);
 157      }
 158  
 159      /**
 160       * What type of configuration is this
 161       *
 162       * Returns one of
 163       *
 164       * 'plugin' for plugin configuration
 165       * 'template' for template configuration
 166       * 'dokuwiki' for core configuration
 167       *
 168       * @return string
 169       */
 170      public function getType() {
 171          if(substr($this->getKey(), 0, 10) == 'plugin' . Configuration::KEYMARKER) {
 172              return 'plugin';
 173          } else if(substr($this->getKey(), 0, 7) == 'tpl' . Configuration::KEYMARKER) {
 174              return 'template';
 175          } else {
 176              return 'dokuwiki';
 177          }
 178      }
 179  
 180      /**
 181       * Build html for label and input of setting
 182       *
 183       * @param \admin_plugin_config $plugin object of config plugin
 184       * @param bool $echo true: show inputted value, when error occurred, otherwise the stored setting
 185       * @return string[] with content array(string $label_html, string $input_html)
 186       */
 187      public function html(\admin_plugin_config $plugin, $echo = false) {
 188          $disable = '';
 189  
 190          if($this->isProtected()) {
 191              $value = $this->protected;
 192              $disable = 'disabled="disabled"';
 193          } else {
 194              if($echo && $this->error) {
 195                  $value = $this->input;
 196              } else {
 197                  $value = is_null($this->local) ? $this->default : $this->local;
 198              }
 199          }
 200  
 201          $key = htmlspecialchars($this->key);
 202          $value = formText($value);
 203  
 204          $label = '<label for="config___' . $key . '">' . $this->prompt($plugin) . '</label>';
 205          $input = '<textarea rows="3" cols="40" id="config___' . $key .
 206              '" name="config[' . $key . ']" class="edit" ' . $disable . '>' . $value . '</textarea>';
 207          return array($label, $input);
 208      }
 209  
 210      /**
 211       * Should the current local value be saved?
 212       *
 213       * @see out() to run when this returns true
 214       * @return bool
 215       */
 216      public function shouldBeSaved() {
 217          if($this->isProtected()) return false;
 218          if($this->local === null) return false;
 219          if($this->default == $this->local) return false;
 220          return true;
 221      }
 222  
 223      /**
 224       * Generate string to save local setting value to file according to $fmt
 225       *
 226       * @see shouldBeSaved() to check if this should be called
 227       * @param string $var name of variable
 228       * @param string $fmt save format
 229       * @return string
 230       */
 231      public function out($var, $fmt = 'php') {
 232          if($fmt != 'php') return '';
 233  
 234          $tr = array("\\" => '\\\\', "'" => '\\\''); // escape the value
 235          $out = '$' . $var . "['" . $this->getArrayKey() . "'] = '" . strtr(cleanText($this->local), $tr) . "';\n";
 236  
 237          return $out;
 238      }
 239  
 240      /**
 241       * Returns the localized prompt
 242       *
 243       * @param \admin_plugin_config $plugin object of config plugin
 244       * @return string text
 245       */
 246      public function prompt(\admin_plugin_config $plugin) {
 247          $prompt = $plugin->getLang($this->key);
 248          if(!$prompt) $prompt = htmlspecialchars(str_replace(array('____', '_'), ' ', $this->key));
 249          return $prompt;
 250      }
 251  
 252      /**
 253       * Is setting protected
 254       *
 255       * @return bool
 256       */
 257      public function isProtected() {
 258          return !is_null($this->protected);
 259      }
 260  
 261      /**
 262       * Is setting the default?
 263       *
 264       * @return bool
 265       */
 266      public function isDefault() {
 267          return !$this->isProtected() && is_null($this->local);
 268      }
 269  
 270      /**
 271       * Has an error?
 272       *
 273       * @return bool
 274       */
 275      public function hasError() {
 276          return $this->error;
 277      }
 278  
 279      /**
 280       * Returns caution
 281       *
 282       * @return false|string caution string, otherwise false for invalid caution
 283       */
 284      public function caution() {
 285          if(empty($this->caution)) return false;
 286          if(!in_array($this->caution, Setting::$validCautions)) {
 287              throw new \RuntimeException(
 288                  'Invalid caution string (' . $this->caution . ') in metadata for setting "' . $this->key . '"'
 289              );
 290          }
 291          return $this->caution;
 292      }
 293  
 294  }