xref: /dokuwiki/lib/plugins/config/core/Setting/Setting.php (revision 54cc7aa41e0f453bd6887b0e79242a139d84a47a) 
1<?php
2
3namespace dokuwiki\plugin\config\core\Setting;
4
5use dokuwiki\plugin\config\core\Configuration;
6
7/**
8 * Class Setting
9 */
10class 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;
16    /** @var mixed the local value of this setting */
17    protected $local;
18    /** @var mixed the protected value of this setting */
19    protected $protected;
20
21    /** @var array valid alerts, images matching the alerts are in the plugin's images directory */
22    static protected $validCautions = ['warning', 'danger', 'security'];
23
24    protected $pattern = '';
25    protected $error = false;            // only used by those classes which error check
26    protected $input;             // only used by those classes which error check
27    protected $caution;           // 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        } elseif (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        } elseif ($echo && $this->error) {
194            $value = $this->input;
195        } else {
196            $value = is_null($this->local) ? $this->default : $this->local;
197        }
198
199        $key = htmlspecialchars($this->key);
200        $value = formText($value);
201
202        $label = '<label for="config___' . $key . '">' . $this->prompt($plugin) . '</label>';
203        $input = '<textarea rows="3" cols="40" id="config___' . $key .
204            '" name="config[' . $key . ']" class="edit" ' . $disable . '>' . $value . '</textarea>';
205        return [$label, $input];
206    }
207
208    /**
209     * Should the current local value be saved?
210     *
211     * @see out() to run when this returns true
212     * @return bool
213     */
214    public function shouldBeSaved() {
215        if($this->isProtected()) return false;
216        if($this->local === null) return false;
217        if($this->default == $this->local) return false;
218        return true;
219    }
220
221    /**
222     * Escaping
223     *
224     * @param string $string
225     * @return string
226     */
227    protected function escape($string) {
228        $tr = ["\\" => '\\\\', "'" => '\\\''];
229        return "'" . strtr(cleanText($string), $tr) . "'";
230    }
231
232    /**
233     * Generate string to save local setting value to file according to $fmt
234     *
235     * @see shouldBeSaved() to check if this should be called
236     * @param string $var name of variable
237     * @param string $fmt save format
238     * @return string
239     */
240    public function out($var, $fmt = 'php') {
241        if ($fmt != 'php') return '';
242
243        if (is_array($this->local)) {
244            $value = 'array(' . implode(', ', array_map([$this, 'escape'], $this->local)) . ')';
245        } else {
246            $value = $this->escape($this->local);
247        }
248
249        $out = '$' . $var . "['" . $this->getArrayKey() . "'] = $value;\n";
250
251        return $out;
252    }
253
254    /**
255     * Returns the localized prompt
256     *
257     * @param \admin_plugin_config $plugin object of config plugin
258     * @return string text
259     */
260    public function prompt(\admin_plugin_config $plugin) {
261        $prompt = $plugin->getLang($this->key);
262        if(!$prompt) $prompt = htmlspecialchars(str_replace(['____', '_'], ' ', $this->key));
263        return $prompt;
264    }
265
266    /**
267     * Is setting protected
268     *
269     * @return bool
270     */
271    public function isProtected() {
272        return !is_null($this->protected);
273    }
274
275    /**
276     * Is setting the default?
277     *
278     * @return bool
279     */
280    public function isDefault() {
281        return !$this->isProtected() && is_null($this->local);
282    }
283
284    /**
285     * Has an error?
286     *
287     * @return bool
288     */
289    public function hasError() {
290        return $this->error;
291    }
292
293    /**
294     * Returns caution
295     *
296     * @return false|string caution string, otherwise false for invalid caution
297     */
298    public function caution() {
299        if(empty($this->caution)) return false;
300        if(!in_array($this->caution, Setting::$validCautions)) {
301            throw new \RuntimeException(
302                'Invalid caution string (' . $this->caution . ') in metadata for setting "' . $this->key . '"'
303            );
304        }
305        return $this->caution;
306    }
307
308}
309