3 * Helper class to keep track of options when mixing links and form elements.
5 * Copyright © 2008, Niklas Laxström
6 * Copyright © 2011, Antoine Musso
7 * Copyright © 2013, Bartosz Dziewoński
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License along
20 * with this program; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 * http://www.gnu.org/copyleft/gpl.html
25 * @author Niklas Laxström
26 * @author Antoine Musso
30 * Helper class to keep track of options when mixing links and form elements.
32 * @todo This badly needs some examples and tests :) The usage in SpecialRecentchanges class is a
33 * good ersatz in the meantime.
35 class FormOptions
implements ArrayAccess
{
36 /** @name Type constants
37 * Used internally to map an option value to a WebRequest accessor
40 /** Mark value for automatic detection (for simple data types only) */
42 /** String type, maps guessType() to WebRequest::getText() */
44 /** Integer type, maps guessType() to WebRequest::getInt() */
46 /** Float type, maps guessType() to WebRequest::getFloat()
50 /** Boolean type, maps guessType() to WebRequest::getBool() */
52 /** Integer type or null, maps to WebRequest::getIntOrNull()
53 * This is useful for the namespace selector.
56 /** Array type, maps guessType() to WebRequest::getArray()
63 * Map of known option names to information about them.
65 * Each value is an array with the following keys:
66 * - 'default' - the default value as passed to add()
67 * - 'value' - current value, start with null, can be set by various functions
68 * - 'consumed' - true/false, whether the option was consumed using
69 * consumeValue() or consumeValues()
70 * - 'type' - one of the type constants (but never AUTO)
72 protected $options = [];
77 * Add an option to be handled by this FormOptions instance.
79 * @param string $name Request parameter name
80 * @param mixed $default Default value when the request parameter is not present
81 * @param int $type One of the type constants (optional, defaults to AUTO)
83 public function add( $name, $default, $type = self
::AUTO
) {
85 $option['default'] = $default;
86 $option['value'] = null;
87 $option['consumed'] = false;
89 if ( $type !== self
::AUTO
) {
90 $option['type'] = $type;
92 $option['type'] = self
::guessType( $default );
95 $this->options
[$name] = $option;
99 * Remove an option being handled by this FormOptions instance. This is the inverse of add().
101 * @param string $name Request parameter name
103 public function delete( $name ) {
104 $this->validateName( $name, true );
105 unset( $this->options
[$name] );
109 * Used to find out which type the data is. All types are defined in the 'Type constants' section
112 * Detection of the INTNULL type is not supported; INT will be assumed if the data is an integer,
113 * MWException will be thrown if it's null.
115 * @param mixed $data Value to guess the type for
116 * @throws MWException If unable to guess the type
117 * @return int Type constant
119 public static function guessType( $data ) {
120 if ( is_bool( $data ) ) {
122 } elseif ( is_int( $data ) ) {
124 } elseif ( is_float( $data ) ) {
126 } elseif ( is_string( $data ) ) {
128 } elseif ( is_array( $data ) ) {
131 throw new MWException( 'Unsupported datatype' );
138 * Verify that the given option name exists.
140 * @param string $name Option name
141 * @param bool $strict Throw an exception when the option doesn't exist instead of returning false
142 * @throws MWException
143 * @return bool True if the option exists, false otherwise
145 public function validateName( $name, $strict = false ) {
146 if ( !isset( $this->options
[$name] ) ) {
148 throw new MWException( "Invalid option $name" );
158 * Use to set the value of an option.
160 * @param string $name Option name
161 * @param mixed $value Value for the option
162 * @param bool $force Whether to set the value when it is equivalent to the default value for this
163 * option (default false).
165 public function setValue( $name, $value, $force = false ) {
166 $this->validateName( $name, true );
168 if ( !$force && $value === $this->options
[$name]['default'] ) {
169 // null default values as unchanged
170 $this->options
[$name]['value'] = null;
172 $this->options
[$name]['value'] = $value;
177 * Get the value for the given option name. Uses getValueReal() internally.
179 * @param string $name Option name
182 public function getValue( $name ) {
183 $this->validateName( $name, true );
185 return $this->getValueReal( $this->options
[$name] );
189 * Return current option value, based on a structure taken from $options.
191 * @param array $option Array structure describing the option
192 * @return mixed Value, or the default value if it is null
194 protected function getValueReal( $option ) {
195 if ( $option['value'] !== null ) {
196 return $option['value'];
198 return $option['default'];
203 * Delete the option value.
204 * This will make future calls to getValue() return the default value.
205 * @param string $name Option name
207 public function reset( $name ) {
208 $this->validateName( $name, true );
209 $this->options
[$name]['value'] = null;
213 * Get the value of given option and mark it as 'consumed'. Consumed options are not returned
214 * by getUnconsumedValues().
216 * @see consumeValues()
217 * @throws MWException If the option does not exist
218 * @param string $name Option name
219 * @return mixed Value, or the default value if it is null
221 public function consumeValue( $name ) {
222 $this->validateName( $name, true );
223 $this->options
[$name]['consumed'] = true;
225 return $this->getValueReal( $this->options
[$name] );
229 * Get the values of given options and mark them as 'consumed'. Consumed options are not returned
230 * by getUnconsumedValues().
232 * @see consumeValue()
233 * @throws MWException If any option does not exist
234 * @param array $names Array of option names as strings
235 * @return array Array of option values, or the default values if they are null
237 public function consumeValues( $names ) {
240 foreach ( $names as $name ) {
241 $this->validateName( $name, true );
242 $this->options
[$name]['consumed'] = true;
243 $out[] = $this->getValueReal( $this->options
[$name] );
250 * @see validateBounds()
251 * @param string $name
255 public function validateIntBounds( $name, $min, $max ) {
256 $this->validateBounds( $name, $min, $max );
260 * Constrain a numeric value for a given option to a given range. The value will be altered to fit
265 * @param string $name Option name
266 * @param int|float $min Minimum value
267 * @param int|float $max Maximum value
268 * @throws MWException If option is not of type INT
270 public function validateBounds( $name, $min, $max ) {
271 $this->validateName( $name, true );
272 $type = $this->options
[$name]['type'];
274 if ( $type !== self
::INT && $type !== self
::FLOAT ) {
275 throw new MWException( "Option $name is not of type INT or FLOAT" );
278 $value = $this->getValueReal( $this->options
[$name] );
279 $value = max( $min, min( $max, $value ) );
281 $this->setValue( $name, $value );
285 * Get all remaining values which have not been consumed by consumeValue() or consumeValues().
287 * @param bool $all Whether to include unchanged options (default: false)
290 public function getUnconsumedValues( $all = false ) {
293 foreach ( $this->options
as $name => $data ) {
294 if ( !$data['consumed'] ) {
295 if ( $all ||
$data['value'] !== null ) {
296 $values[$name] = $this->getValueReal( $data );
305 * Return options modified as an array ( name => value )
308 public function getChangedValues() {
311 foreach ( $this->options
as $name => $data ) {
312 if ( $data['value'] !== null ) {
313 $values[$name] = $data['value'];
321 * Format options to an array ( name => value )
324 public function getAllValues() {
327 foreach ( $this->options
as $name => $data ) {
328 $values[$name] = $this->getValueReal( $data );
337 * Fetch values for all options (or selected options) from the given WebRequest, making them
338 * available for accessing with getValue() or consumeValue() etc.
340 * @param WebRequest $r The request to fetch values from
341 * @param array|null $optionKeys Which options to fetch the values for (default:
342 * all of them). Note that passing an empty array will also result in
343 * values for all keys being fetched.
344 * @throws MWException If the type of any option is invalid
346 public function fetchValuesFromRequest( WebRequest
$r, $optionKeys = null ) {
347 if ( !$optionKeys ) {
348 $optionKeys = array_keys( $this->options
);
351 foreach ( $optionKeys as $name ) {
352 $default = $this->options
[$name]['default'];
353 $type = $this->options
[$name]['type'];
357 $value = $r->getBool( $name, $default );
360 $value = $r->getInt( $name, $default );
363 $value = $r->getFloat( $name, $default );
366 $value = $r->getText( $name, $default );
369 $value = $r->getIntOrNull( $name );
372 $value = $r->getArray( $name );
375 throw new MWException( 'Unsupported datatype' );
378 if ( $value !== null ) {
379 $this->options
[$name]['value'] = $value === $default ?
null : $value;
384 /** @name ArrayAccess functions
385 * These functions implement the ArrayAccess PHP interface.
386 * @see https://www.php.net/manual/en/class.arrayaccess.php
391 * Whether the option exists.
392 * @param string $name
395 public function offsetExists( $name ) {
396 return isset( $this->options
[$name] );
400 * Retrieve an option value.
401 * @param string $name
404 public function offsetGet( $name ) {
405 return $this->getValue( $name );
409 * Set an option to given value.
410 * @param string $name
411 * @param mixed $value
413 public function offsetSet( $name, $value ) {
414 $this->setValue( $name, $value );
419 * @param string $name
421 public function offsetUnset( $name ) {
422 $this->delete( $name );