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