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()
49 /** Boolean type, maps guessType() to WebRequest::getBool() */
51 /** Integer type or null, maps to WebRequest::getIntOrNull()
52 * This is useful for the namespace selector.
58 * Map of known option names to information about them.
60 * Each value is an array with the following keys:
61 * - 'default' - the default value as passed to add()
62 * - 'value' - current value, start with null, can be set by various functions
63 * - 'consumed' - true/false, whether the option was consumed using
64 * consumeValue() or consumeValues()
65 * - 'type' - one of the type constants (but never AUTO)
67 protected $options = array();
72 * Add an option to be handled by this FormOptions instance.
74 * @param string $name Request parameter name
75 * @param mixed $default Default value when the request parameter is not present
76 * @param int $type One of the type constants (optional, defaults to AUTO)
78 public function add( $name, $default, $type = self
::AUTO
) {
80 $option['default'] = $default;
81 $option['value'] = null;
82 $option['consumed'] = false;
84 if ( $type !== self
::AUTO
) {
85 $option['type'] = $type;
87 $option['type'] = self
::guessType( $default );
90 $this->options
[$name] = $option;
94 * Remove an option being handled by this FormOptions instance. This is the inverse of add().
96 * @param string $name Request parameter name
98 public function delete( $name ) {
99 $this->validateName( $name, true );
100 unset( $this->options
[$name] );
104 * Used to find out which type the data is. All types are defined in the 'Type constants' section
107 * Detection of the INTNULL type is not supported; INT will be assumed if the data is an integer,
108 * MWException will be thrown if it's null.
110 * @param mixed $data Value to guess the type for
111 * @throws MWException If unable to guess the type
112 * @return int Type constant
114 public static function guessType( $data ) {
115 if ( is_bool( $data ) ) {
117 } elseif ( is_int( $data ) ) {
119 } elseif ( is_float( $data ) ) {
121 } elseif ( is_string( $data ) ) {
124 throw new MWException( 'Unsupported datatype' );
131 * Verify that the given option name exists.
133 * @param string $name Option name
134 * @param bool $strict Throw an exception when the option doesn't exist instead of returning false
135 * @throws MWException
136 * @return bool True if the option exists, false otherwise
138 public function validateName( $name, $strict = false ) {
139 if ( !isset( $this->options
[$name] ) ) {
141 throw new MWException( "Invalid option $name" );
151 * Use to set the value of an option.
153 * @param string $name Option name
154 * @param mixed $value Value for the option
155 * @param bool $force Whether to set the value when it is equivalent to the default value for this
156 * option (default false).
158 public function setValue( $name, $value, $force = false ) {
159 $this->validateName( $name, true );
161 if ( !$force && $value === $this->options
[$name]['default'] ) {
162 // null default values as unchanged
163 $this->options
[$name]['value'] = null;
165 $this->options
[$name]['value'] = $value;
170 * Get the value for the given option name. Uses getValueReal() internally.
172 * @param string $name Option name
175 public function getValue( $name ) {
176 $this->validateName( $name, true );
178 return $this->getValueReal( $this->options
[$name] );
182 * Return current option value, based on a structure taken from $options.
184 * @param array $option Array structure describing the option
185 * @return mixed Value, or the default value if it is null
187 protected function getValueReal( $option ) {
188 if ( $option['value'] !== null ) {
189 return $option['value'];
191 return $option['default'];
196 * Delete the option value.
197 * This will make future calls to getValue() return the default value.
198 * @param string $name Option name
200 public function reset( $name ) {
201 $this->validateName( $name, true );
202 $this->options
[$name]['value'] = null;
206 * Get the value of given option and mark it as 'consumed'. Consumed options are not returned
207 * by getUnconsumedValues().
209 * @see consumeValues()
210 * @throws MWException If the option does not exist
211 * @param string $name Option name
212 * @return mixed Value, or the default value if it is null
214 public function consumeValue( $name ) {
215 $this->validateName( $name, true );
216 $this->options
[$name]['consumed'] = true;
218 return $this->getValueReal( $this->options
[$name] );
222 * Get the values of given options and mark them as 'consumed'. Consumed options are not returned
223 * by getUnconsumedValues().
225 * @see consumeValue()
226 * @throws MWException If any option does not exist
227 * @param array $names Array of option names as strings
228 * @return array Array of option values, or the default values if they are null
230 public function consumeValues( $names ) {
233 foreach ( $names as $name ) {
234 $this->validateName( $name, true );
235 $this->options
[$name]['consumed'] = true;
236 $out[] = $this->getValueReal( $this->options
[$name] );
243 * @see validateBounds()
245 public function validateIntBounds( $name, $min, $max ) {
246 $this->validateBounds( $name, $min, $max );
250 * Constrain a numeric value for a given option to a given range. The value will be altered to fit
255 * @param string $name Option name
256 * @param int|float $min Minimum value
257 * @param int|float $max Maximum value
258 * @throws MWException If option is not of type INT
260 public function validateBounds( $name, $min, $max ) {
261 $this->validateName( $name, true );
262 $type = $this->options
[$name]['type'];
264 if ( $type !== self
::INT && $type !== self
::FLOAT ) {
265 throw new MWException( "Option $name is not of type INT or FLOAT" );
268 $value = $this->getValueReal( $this->options
[$name] );
269 $value = max( $min, min( $max, $value ) );
271 $this->setValue( $name, $value );
275 * Get all remaining values which have not been consumed by consumeValue() or consumeValues().
277 * @param bool $all Whether to include unchanged options (default: false)
280 public function getUnconsumedValues( $all = false ) {
283 foreach ( $this->options
as $name => $data ) {
284 if ( !$data['consumed'] ) {
285 if ( $all ||
$data['value'] !== null ) {
286 $values[$name] = $this->getValueReal( $data );
295 * Return options modified as an array ( name => value )
298 public function getChangedValues() {
301 foreach ( $this->options
as $name => $data ) {
302 if ( $data['value'] !== null ) {
303 $values[$name] = $data['value'];
311 * Format options to an array ( name => value )
314 public function getAllValues() {
317 foreach ( $this->options
as $name => $data ) {
318 $values[$name] = $this->getValueReal( $data );
327 * Fetch values for all options (or selected options) from the given WebRequest, making them
328 * available for accessing with getValue() or consumeValue() etc.
330 * @param WebRequest $r The request to fetch values from
331 * @param array $optionKeys Which options to fetch the values for (default:
332 * all of them). Note that passing an empty array will also result in
333 * values for all keys being fetched.
334 * @throws MWException If the type of any option is invalid
336 public function fetchValuesFromRequest( WebRequest
$r, $optionKeys = null ) {
337 if ( !$optionKeys ) {
338 $optionKeys = array_keys( $this->options
);
341 foreach ( $optionKeys as $name ) {
342 $default = $this->options
[$name]['default'];
343 $type = $this->options
[$name]['type'];
347 $value = $r->getBool( $name, $default );
350 $value = $r->getInt( $name, $default );
353 $value = $r->getFloat( $name, $default );
356 $value = $r->getText( $name, $default );
359 $value = $r->getIntOrNull( $name );
362 throw new MWException( 'Unsupported datatype' );
365 if ( $value !== null ) {
366 $this->options
[$name]['value'] = $value === $default ?
null : $value;
371 /** @name ArrayAccess functions
372 * These functions implement the ArrayAccess PHP interface.
373 * @see http://php.net/manual/en/class.arrayaccess.php
377 * Whether the option exists.
380 public function offsetExists( $name ) {
381 return isset( $this->options
[$name] );
385 * Retrieve an option value.
388 public function offsetGet( $name ) {
389 return $this->getValue( $name );
393 * Set an option to given value.
395 public function offsetSet( $name, $value ) {
396 $this->setValue( $name, $value );
402 public function offsetUnset( $name ) {
403 $this->delete( $name );