[ Index ] |
PHP Cross Reference of DokuWiki |
[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 * Escaping 225 * 226 * @param string $string 227 * @return string 228 */ 229 protected function escape($string) { 230 $tr = array("\\" => '\\\\', "'" => '\\\''); 231 return "'" . strtr(cleanText($string), $tr) . "'"; 232 } 233 234 /** 235 * Generate string to save local setting value to file according to $fmt 236 * 237 * @see shouldBeSaved() to check if this should be called 238 * @param string $var name of variable 239 * @param string $fmt save format 240 * @return string 241 */ 242 public function out($var, $fmt = 'php') { 243 if ($fmt != 'php') return ''; 244 245 if (is_array($this->local)) { 246 $value = 'array(' . join(', ', array_map([$this, 'escape'], $this->local)) . ')'; 247 } else { 248 $value = $this->escape($this->local); 249 } 250 251 $out = '$' . $var . "['" . $this->getArrayKey() . "'] = $value;\n"; 252 253 return $out; 254 } 255 256 /** 257 * Returns the localized prompt 258 * 259 * @param \admin_plugin_config $plugin object of config plugin 260 * @return string text 261 */ 262 public function prompt(\admin_plugin_config $plugin) { 263 $prompt = $plugin->getLang($this->key); 264 if(!$prompt) $prompt = htmlspecialchars(str_replace(array('____', '_'), ' ', $this->key)); 265 return $prompt; 266 } 267 268 /** 269 * Is setting protected 270 * 271 * @return bool 272 */ 273 public function isProtected() { 274 return !is_null($this->protected); 275 } 276 277 /** 278 * Is setting the default? 279 * 280 * @return bool 281 */ 282 public function isDefault() { 283 return !$this->isProtected() && is_null($this->local); 284 } 285 286 /** 287 * Has an error? 288 * 289 * @return bool 290 */ 291 public function hasError() { 292 return $this->error; 293 } 294 295 /** 296 * Returns caution 297 * 298 * @return false|string caution string, otherwise false for invalid caution 299 */ 300 public function caution() { 301 if(empty($this->caution)) return false; 302 if(!in_array($this->caution, Setting::$validCautions)) { 303 throw new \RuntimeException( 304 'Invalid caution string (' . $this->caution . ') in metadata for setting "' . $this->key . '"' 305 ); 306 } 307 return $this->caution; 308 } 309 310 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body