[ 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="http://www.dokuwiki.org/config:startpage">' . $out . '</a>'; 141 } else { 142 return '<a href="http://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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body