Helper class to keep track of options when mixing links and form elements. More...

Inheritance diagram for FormOptions:

Public Member Functions
	add ($name, $default, $type=self::AUTO)
	Add an option to be handled by this FormOptions instance.
	consumeValue ($name)
	Get the value of given option and mark it as 'consumed'.
	consumeValues ($names)
	Get the values of given options and mark them as 'consumed'.
	delete ($name)
	Remove an option being handled by this FormOptions instance.
	fetchValuesFromRequest (WebRequest $r, $optionKeys=null)
	Fetch values for all options (or selected options) from the given WebRequest, making them available for accessing with getValue() or consumeValue() etc.
	getAllValues ()
	Format options to an array ( name => value )
	getChangedValues ()
	Return options modified as an array ( name => value )
	getUnconsumedValues ($all=false)
	Get all remaining values which have not been consumed by consumeValue() or consumeValues().
	getValue ($name)
	Get the value for the given option name.
	reset ($name)
	Delete the option value.
	setValue ($name, $value, $force=false)
	Use to set the value of an option.
	validateIntBounds ($name, $min, $max)
	Validate and set an option integer value The value will be altered to fit in the range.
	validateName ($name, $strict=false)
	Verify that the given option name exists.
ArrayAccess functions
These functions implement the ArrayAccess PHP interface. See also: http://php.net/manual/en/class.arrayaccess.php
	offsetExists ($name)
	Whether the option exists.
	offsetGet ($name)
	Retrieve an option value.
	offsetSet ($name, $value)
	Set an option to given value.
	offsetUnset ($name)
	Delete the option.
Static Public Member Functions
static	guessType ($data)
	Used to find out which type the data is.
Public Attributes
Type constants
Used internally to map an option value to a WebRequest accessor
const	AUTO = -1
	Mark value for automatic detection (for simple data types only)
const	STRING = 0
	String type, maps guessType() to WebRequest::getText()
const	INT = 1
	Integer type, maps guessType() to WebRequest::getInt()
const	BOOL = 2
	Boolean type, maps guessType() to WebRequest::getBool()
const	INTNULL = 3
	Integer type or null, maps to WebRequest::getIntOrNull() This is useful for the namespace selector.
Protected Member Functions
	getValueReal ($option)
	Return current option value, based on a structure taken from $options.
Protected Attributes
	$options = array()
	Map of known option names to information about them.

Detailed Description

Helper class to keep track of options when mixing links and form elements.

Todo:: This badly needs some examples and tests :) The usage in SpecialRecentchanges class is a good ersatz in the meantime.

Definition at line 34 of file FormOptions.php.

Member Function Documentation

FormOptions::add	(	$	name,
		$	default,
		$	type = `self::AUTO`
	)

Add an option to be handled by this FormOptions instance.

Parameters:

string	$name	Request parameter name
mixed	$default	Default value when the request parameter is not present
int	$type	One of the type constants (optional, defaults to AUTO)

Definition at line 74 of file FormOptions.php.

References $name, array(), guessType(), and options().

Referenced by SpecialLog\execute(), and SpecialNewpages\setup().

FormOptions::consumeValue ( $ name )

Get the value of given option and mark it as 'consumed'.

Consumed options are not returned by getUnconsumedValues().

See also:: consumeValues()

Exceptions:

MWException If the option does not exist

Parameters:

string $name Option name

Returns:: mixed Value, or the default value if it is null

Definition at line 208 of file FormOptions.php.

References $name, getValueReal(), options(), and validateName().

FormOptions::consumeValues ( $ names )

Get the values of given options and mark them as 'consumed'.

Consumed options are not returned by getUnconsumedValues().

See also:: consumeValue()

Exceptions:

MWException If any option does not exist

Parameters:

array $names Array of option names as strings

Returns:: array Array of option values, or the default values if they are null

Definition at line 224 of file FormOptions.php.

References $name, $out, array(), as, getValueReal(), options(), and validateName().

FormOptions::delete ( $ name )

Remove an option being handled by this FormOptions instance.

This is the inverse of add().

Parameters:

string $name Request parameter name

Definition at line 94 of file FormOptions.php.

References $name, options(), and validateName().

FormOptions::fetchValuesFromRequest	(	WebRequest $	r,
		$	optionKeys = `null`
	)

Fetch values for all options (or selected options) from the given WebRequest, making them available for accessing with getValue() or consumeValue() etc.

Parameters:

WebRequest	$r	The request to fetch values from
array	$optionKeys	Which options to fetch the values for (default: all of them). Note that passing an empty array will also result in values for all keys being fetched.

Exceptions:

MWException If the type of any option is invalid

Definition at line 320 of file FormOptions.php.

References $name, $value, as, WebRequest\getBool(), WebRequest\getInt(), WebRequest\getIntOrNull(), WebRequest\getText(), and options().

Referenced by SpecialNewpages\setup().

FormOptions::getAllValues ( )

Format options to an array ( name => value )

Returns:: array

Definition at line 298 of file FormOptions.php.

References $name, array(), as, getValueReal(), and options().

FormOptions::getChangedValues ( )

Return options modified as an array ( name => value )

Returns:: array

Definition at line 282 of file FormOptions.php.

References $name, array(), as, and options().

FormOptions::getUnconsumedValues ( $ all = false )

Get all remaining values which have not been consumed by consumeValue() or consumeValues().

Parameters:

bool $all Whether to include unchanged options (default: false)

Returns:: array

Definition at line 264 of file FormOptions.php.

References $name, array(), as, getValueReal(), and options().

FormOptions::getValue ( $ name )

Get the value for the given option name.

Uses getValueReal() internally.

Parameters:

string $name Option name

Returns:: mixed

Definition at line 169 of file FormOptions.php.

References $name, getValueReal(), options(), and validateName().

Referenced by offsetGet(), and SpecialLog\show().

FormOptions::getValueReal ( $ option ) [protected]

Return current option value, based on a structure taken from $options.

Parameters:

array $option Array structure describing the option

Returns:: mixed Value, or the default value if it is null

Definition at line 181 of file FormOptions.php.

Referenced by consumeValue(), consumeValues(), getAllValues(), getUnconsumedValues(), getValue(), and validateIntBounds().

static FormOptions::guessType ( $ data ) [static]

Used to find out which type the data is.

All types are defined in the 'Type constants' section of this class.

Detection of the INTNULL type is not supported; INT will be assumed if the data is an integer, MWException will be thrown if it's null.

Parameters:

mixed $data Value to guess the type for

Exceptions:

MWException If unable to guess the type

Returns:: int Type constant

Definition at line 110 of file FormOptions.php.

References BOOL, INT, and STRING.

Referenced by add().

FormOptions::offsetExists ( $ name )

Whether the option exists.

Definition at line 358 of file FormOptions.php.

References $name, and options().

FormOptions::offsetGet ( $ name )

Retrieve an option value.

Definition at line 363 of file FormOptions.php.

References $name, and getValue().

FormOptions::offsetSet	(	$	name,
		$	value
	)

Set an option to given value.

Definition at line 368 of file FormOptions.php.

References $name, $value, and setValue().

FormOptions::offsetUnset ( $ name )

Delete the option.

Definition at line 373 of file FormOptions.php.

References $name.

FormOptions::reset ( $ name )

Delete the option value.

This will make future calls to getValue() return the default value.

Parameters:

string $name Option name

Definition at line 194 of file FormOptions.php.

References $name, options(), and validateName().

Referenced by SpecialRecentChanges\buildMainQueryConds().

FormOptions::setValue	(	$	name,
		$	value,
		$	force = `false`
	)

Use to set the value of an option.

Parameters:

string	$name	Option name
mixed	$value	Value for the option
bool	$force	Whether to set the value when it is equivalent to the default value for this option (default false).

Definition at line 152 of file FormOptions.php.

References $name, $value, options(), and validateName().

Referenced by offsetSet(), SpecialLog\parseParams(), SpecialNewpages\setup(), and validateIntBounds().

FormOptions::validateIntBounds	(	$	name,
		$	min,
		$	max
	)

Validate and set an option integer value The value will be altered to fit in the range.

Parameters:

string	$name	option name
int	$min	minimum value
int	$max	maximum value

Exceptions:

MWException If option is not of type INT

Definition at line 245 of file FormOptions.php.

References $name, $value, getValueReal(), options(), setValue(), and validateName().

Referenced by SpecialNewpages\setup().

FormOptions::validateName	(	$	name,
		$	strict = `false`
	)

Verify that the given option name exists.

Parameters:

string	$name	Option name
bool	$strict	Throw an exception when the option doesn't exist instead of returning false

Exceptions:

MWException

Returns:: bool True if the option exists, false otherwise

Definition at line 132 of file FormOptions.php.

References $name, and options().

Referenced by consumeValue(), consumeValues(), delete(), getValue(), reset(), setValue(), and validateIntBounds().

Member Data Documentation

FormOptions::$options = array() [protected]

Map of known option names to information about them.

Each value is an array with the following keys:

'default' - the default value as passed to add()
'value' - current value, start with null, can be set by various functions
'consumed' - true/false, whether the option was consumed using consumeValue() or consumeValues()
'type' - one of the type constants (but never AUTO)

Definition at line 63 of file FormOptions.php.

const FormOptions::AUTO = -1

Mark value for automatic detection (for simple data types only)

Definition at line 40 of file FormOptions.php.

const FormOptions::BOOL = 2

Boolean type, maps guessType() to WebRequest::getBool()

Definition at line 46 of file FormOptions.php.

Referenced by FormOptionsTest\assertGuessBoolean(), and guessType().

const FormOptions::INT = 1

Integer type, maps guessType() to WebRequest::getInt()

Definition at line 44 of file FormOptions.php.

Referenced by guessType(), and FormOptionsInitializationTest\testAddIntegers().