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