3 * Helper class to keep track of options when mixing links and form elements.
5 * Copyright © 2008, Niklas Laxstiröm
6 * Copyright © 2011, Antoine Musso
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License along
19 * with this program; if not, write to the Free Software Foundation, Inc.,
20 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21 * http://www.gnu.org/copyleft/gpl.html
24 * @author Niklas Laxström
25 * @author Antoine Musso
29 * Helper class to keep track of options when mixing links and form elements.
31 * @todo This badly need some examples and tests :-)
33 class FormOptions
implements ArrayAccess
{
34 /** @name Type constants
35 * Used internally to map an option value to a WebRequest accessor
38 /** Mark value for automatic detection (for simple data types only) */
40 /** String type, maps guessType() to WebRequest::getText() */
42 /** Integer type, maps guessType() to WebRequest::getInt() */
44 /** Boolean type, maps guessType() to WebRequest::getBool() */
46 /** Integer type or null, maps to WebRequest::getIntOrNull()
47 * This is useful for the namespace selector.
55 protected $options = array();
59 public function add( $name, $default, $type = self
::AUTO
) {
61 $option['default'] = $default;
62 $option['value'] = null;
63 $option['consumed'] = false;
65 if ( $type !== self
::AUTO
) {
66 $option['type'] = $type;
68 $option['type'] = self
::guessType( $default );
71 $this->options
[$name] = $option;
74 public function delete( $name ) {
75 $this->validateName( $name, true );
76 unset( $this->options
[$name] );
80 * Used to find out which type the data is.
81 * All types are defined in the 'Type constants' section of this class
82 * Please note we do not support detection of INTNULL MediaWiki type
83 * which will be assumed as INT if the data is an integer.
85 * @param $data Mixed: value to guess type for
86 * @exception MWException Unsupported datatype
87 * @return int Type constant
89 public static function guessType( $data ) {
90 if ( is_bool( $data ) ) {
92 } elseif ( is_int( $data ) ) {
94 } elseif ( is_string( $data ) ) {
97 throw new MWException( 'Unsupported datatype' );
104 * Verify the given option name exist.
106 * @param $name String: option name
107 * @param $strict Boolean: throw an exception when the option does not exist (default false)
108 * @return Boolean: true if option exist, false otherwise
110 public function validateName( $name, $strict = false ) {
111 if ( !isset( $this->options
[$name] ) ) {
113 throw new MWException( "Invalid option $name" );
122 * Use to set the value of an option.
124 * @param $name String: option name
125 * @param $value Mixed: value for the option
126 * @param $force Boolean: whether to set the value when it is equivalent to the default value for this option (default false).
129 public function setValue( $name, $value, $force = false ) {
130 $this->validateName( $name, true );
132 if ( !$force && $value === $this->options
[$name]['default'] ) {
133 // null default values as unchanged
134 $this->options
[$name]['value'] = null;
136 $this->options
[$name]['value'] = $value;
141 * Get the value for the given option name.
142 * Internally use getValueReal()
144 * @param $name String: option name
147 public function getValue( $name ) {
148 $this->validateName( $name, true );
150 return $this->getValueReal( $this->options
[$name] );
155 * @param $option Array: array structure describing the option
156 * @return Mixed. Value or the default value if it is null
158 protected function getValueReal( $option ) {
159 if ( $option['value'] !== null ) {
160 return $option['value'];
162 return $option['default'];
167 * Delete the option value.
168 * This will make future calls to getValue() return the default value.
169 * @param $name String: option name
172 public function reset( $name ) {
173 $this->validateName( $name, true );
174 $this->options
[$name]['value'] = null;
179 * @param $name String: option name
182 public function consumeValue( $name ) {
183 $this->validateName( $name, true );
184 $this->options
[$name]['consumed'] = true;
186 return $this->getValueReal( $this->options
[$name] );
191 * @param $names Array: array of option names
194 public function consumeValues( /*Array*/ $names ) {
197 foreach ( $names as $name ) {
198 $this->validateName( $name, true );
199 $this->options
[$name]['consumed'] = true;
200 $out[] = $this->getValueReal( $this->options
[$name] );
207 * Validate and set an option integer value
208 * The value will be altered to fit in the range.
210 * @param $name String: option name
211 * @param $min Int: minimum value
212 * @param $max Int: maximum value
213 * @exception MWException Option is not of type int
216 public function validateIntBounds( $name, $min, $max ) {
217 $this->validateName( $name, true );
219 if ( $this->options
[$name]['type'] !== self
::INT ) {
220 throw new MWException( "Option $name is not of type int" );
223 $value = $this->getValueReal( $this->options
[$name] );
224 $value = max( $min, min( $max, $value ) );
226 $this->setValue( $name, $value );
230 * Getting the data out for use
231 * @param $all Boolean: whether to include unchanged options (default: false)
234 public function getUnconsumedValues( $all = false ) {
237 foreach ( $this->options
as $name => $data ) {
238 if ( !$data['consumed'] ) {
239 if ( $all ||
$data['value'] !== null ) {
240 $values[$name] = $this->getValueReal( $data );
249 * Return options modified as an array ( name => value )
252 public function getChangedValues() {
255 foreach ( $this->options
as $name => $data ) {
256 if ( $data['value'] !== null ) {
257 $values[$name] = $data['value'];
265 * Format options to an array ( name => value)
268 public function getAllValues() {
271 foreach ( $this->options
as $name => $data ) {
272 $values[$name] = $this->getValueReal( $data );
280 public function fetchValuesFromRequest( WebRequest
$r, $values = false ) {
282 $values = array_keys( $this->options
);
285 foreach ( $values as $name ) {
286 $default = $this->options
[$name]['default'];
287 $type = $this->options
[$name]['type'];
291 $value = $r->getBool( $name, $default ); break;
293 $value = $r->getInt( $name, $default ); break;
295 $value = $r->getText( $name, $default ); break;
297 $value = $r->getIntOrNull( $name ); break;
299 throw new MWException( 'Unsupported datatype' );
302 if ( $value !== null ) {
303 $this->options
[$name]['value'] = $value === $default ?
null : $value;
308 /** @name ArrayAccess functions
309 * Those function implements PHP ArrayAccess interface
310 * @see http://php.net/manual/en/class.arrayaccess.php
314 * Whether option exist
317 public function offsetExists( $name ) {
318 return isset( $this->options
[$name] );
321 * Retrieve an option value
324 public function offsetGet( $name ) {
325 return $this->getValue( $name );
327 /** Set an option to given value */
328 public function offsetSet( $name, $value ) {
329 $this->setValue( $name, $value );
331 /** Delete the option */
332 public function offsetUnset( $name ) {
333 $this->delete( $name );