summaryrefslogtreecommitdiff
path: root/includes/FormOptions.php
blob: ccc87d8a23c7d37a48743652fcd6dd7cbae420f8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
<?php
/**
 * Helper class to keep track of options when mixing links and form elements.
 * @todo This badly need some examples and tests :-)
 *
 * Copyright © 2008, Niklas Laxstiröm
 *
 * Copyright © 2011, Antoine Musso
 *
 * @author Niklas Laxström
 * @author Antoine Musso 
 */

class FormOptions implements ArrayAccess {
	/** @name Type constants
	 * Used internally to map an option value to a WebRequest accessor
	 */
	/* @{ */
	/** Mark value for automatic detection (for simple data types only) */
	const AUTO = -1;
	/** String type, maps guessType() to WebRequest::getText() */
	const STRING = 0;
	/** Integer type, maps guessType() to WebRequest::getInt() */
	const INT = 1;
	/** Boolean type, maps guessType() to WebRequest::getBool() */
	const BOOL = 2;
	/** Integer type or null, maps to WebRequest::getIntOrNull()
	 * This is useful for the namespace selector.
	 */
	const INTNULL = 3;
	/* @} */

	/**
	 * @todo Document!
	 */
	protected $options = array();

	# Setting up

	public function add( $name, $default, $type = self::AUTO ) {
		$option = array();
		$option['default'] = $default;
		$option['value'] = null;
		$option['consumed'] = false;

		if ( $type !== self::AUTO ) {
			$option['type'] = $type;
		} else {
			$option['type'] = self::guessType( $default );
		}

		$this->options[$name] = $option;
	}

	public function delete( $name ) {
		$this->validateName( $name, true );
		unset( $this->options[$name] );
	}

	/**
	 * Used to find out which type the data is.
	 * All types are defined in the 'Type constants' section of this class
	 * Please note we do not support detection of INTNULL MediaWiki type
	 * which will be assumed as INT if the data is an integer.
	 *
	 * @param $data Mixed: value to guess type for
	 * @exception MWException Unsupported datatype
	 * @return Type constant 
	 */
	public static function guessType( $data ) {
		if ( is_bool( $data ) ) {
			return self::BOOL;
		} elseif ( is_int( $data ) ) {
			return self::INT;
		} elseif ( is_string( $data ) ) {
			return self::STRING;
		} else {
			throw new MWException( 'Unsupported datatype' );
		}
	}

	# Handling values

	/**
	 * Verify the given option name exist.
	 *
	 * @param $name String: option name
	 * @param $strict Boolean: throw an exception when the option does not exist (default false)
	 * @return Boolean: true if option exist, false otherwise
	 */
	public function validateName( $name, $strict = false ) {
		if ( !isset( $this->options[$name] ) ) {
			if ( $strict ) {
				throw new MWException( "Invalid option $name" );
			} else {
				return false;
			}
		}
		return true;
	}

	/**
	 * Use to set the value of an option.
	 *
	 * @param $name String: option name
	 * @param $value Mixed: value for the option
	 * @param $force Boolean: whether to set the value when it is equivalent to the default value for this option (default false).
	 * @return null
	 */
	public function setValue( $name, $value, $force = false ) {
		$this->validateName( $name, true );

		if ( !$force && $value === $this->options[$name]['default'] ) {
			// null default values as unchanged
			$this->options[$name]['value'] = null;
		} else {
			$this->options[$name]['value'] = $value;
		}
	}

	/**
	 * Get the value for the given option name.
	 * Internally use getValueReal()
	 *
	 * @param $name String: option name
	 * @return Mixed
	 */
	public function getValue( $name ) {
		$this->validateName( $name, true );

		return $this->getValueReal( $this->options[$name] );
	}

	/**
	 * @todo Document
	 * @param $option Array: array structure describing the option
	 * @return Mixed. Value or the default value if it is null
	 */
	protected function getValueReal( $option ) {
		if ( $option['value'] !== null ) {
			return $option['value'];
		} else {
			return $option['default'];
		}
	}

	/**
	 * Delete the option value.
	 * This will make future calls to getValue()  return the default value.
	 * @param $name String: option name
	 * @return null
	 */
	public function reset( $name ) {
		$this->validateName( $name, true );
		$this->options[$name]['value'] = null;
	}

	/**
	 * @todo Document
	 * @param $name String: option name
	 * @return null
	 */
	public function consumeValue( $name ) {
		$this->validateName( $name, true );
		$this->options[$name]['consumed'] = true;

		return $this->getValueReal( $this->options[$name] );
	}

	/**
	 * @todo Document
	 * @param $names Array: array of option names
	 * @return null
	 */
	public function consumeValues( /*Array*/ $names ) {
		$out = array();

		foreach ( $names as $name ) {
			$this->validateName( $name, true );
			$this->options[$name]['consumed'] = true;
			$out[] = $this->getValueReal( $this->options[$name] );
		}

		return $out;
	}

	/**
	 * Validate and set an option integer value
	 * The value will be altered to fit in the range. 
	 *
	 * @param $name String: option name
	 * @param $min Int: minimum value
	 * @param $max Int: maximum value
	 * @exception MWException Option is not of type int
	 * @return null
	 */
	public function validateIntBounds( $name, $min, $max ) {
		$this->validateName( $name, true );

		if ( $this->options[$name]['type'] !== self::INT ) {
			throw new MWException( "Option $name is not of type int" );
		}

		$value = $this->getValueReal( $this->options[$name] );
		$value = max( $min, min( $max, $value ) );

		$this->setValue( $name, $value );
	}

	/**
	 * Getting the data out for use
	 * @param $all Boolean: whether to include unchanged options (default: false)
	 * @return Array
	 */
	public function getUnconsumedValues( $all = false ) {
		$values = array();

		foreach ( $this->options as $name => $data ) {
			if ( !$data['consumed'] ) {
				if ( $all || $data['value'] !== null ) {
					$values[$name] = $this->getValueReal( $data );
				}
			}
		}

		return $values;
	}

	/**
	 * Return options modified as an array ( name => value )
	 * @return Array
	 */
	public function getChangedValues() {
		$values = array();

		foreach ( $this->options as $name => $data ) {
			if ( $data['value'] !== null ) {
				$values[$name] = $data['value'];
			}
		}

		return $values;
	}

	/**
	 * Format options to an array ( name => value)
	 * @return Array
	 */
	public function getAllValues() {
		$values = array();

		foreach ( $this->options as $name => $data ) {
			$values[$name] = $this->getValueReal( $data );
		}

		return $values;
	}

	# Reading values

	public function fetchValuesFromRequest( WebRequest $r, $values = false ) {
		if ( !$values ) {
			$values = array_keys( $this->options );
		}

		foreach ( $values as $name ) {
			$default = $this->options[$name]['default'];
			$type = $this->options[$name]['type'];

			switch( $type ) {
				case self::BOOL:
					$value = $r->getBool( $name, $default ); break;
				case self::INT:
					$value = $r->getInt( $name, $default ); break;
				case self::STRING:
					$value = $r->getText( $name, $default ); break;
				case self::INTNULL:
					$value = $r->getIntOrNull( $name ); break;
				default:
					throw new MWException( 'Unsupported datatype' );
			}

			if ( $value !== null ) {
				$this->options[$name]['value'] = $value === $default ? null : $value;
			}
		}
	}

	/** @name ArrayAccess functions
	 * Those function implements PHP ArrayAccess interface
	 * @see http://php.net/manual/en/class.arrayaccess.php
	 */
	/* @{ */
	/** Whether option exist*/
	public function offsetExists( $name ) {
		return isset( $this->options[$name] );
	}
	/** Retrieve an option value */
	public function offsetGet( $name ) {
		return $this->getValue( $name );
	}
	/**	Set an option to given value */
	public function offsetSet( $name, $value ) {
		$this->setValue( $name, $value );
	}
	/**	Delete the option */
	public function offsetUnset( $name ) {
		$this->delete( $name );
	}
	/* @} */
}