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

Inheritance diagram for FormOptions:

Collaboration diagram for FormOptions:

Public Member Functions
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. More...

	offsetGet ( $name)
	Retrieve an option value. More...

	offsetSet ( $name, $value)
	Set an option to given value. More...

	offsetUnset ( $name)
	Delete the option. More...

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) More...

const	STRING = 0
	String type, maps guessType() to WebRequest::getText() More...

const	INT = 1
	Integer type, maps guessType() to WebRequest::getInt() More...

const	FLOAT = 4
	Float type, maps guessType() to WebRequest::getFloat() More...

const	BOOL = 2
	Boolean type, maps guessType() to WebRequest::getBool() More...

const	INTNULL = 3
	Integer type or null, maps to WebRequest::getIntOrNull() This is useful for the namespace selector. More...

	$options = array()
	Map of known option names to information about them. More...

	add ( $name, $default, $type=self::AUTO)
	Add an option to be handled by this FormOptions instance. More...

	delete ( $name)
	Remove an option being handled by this FormOptions instance. More...

	validateName ( $name, $strict=false)
	Verify that the given option name exists. More...

	setValue ( $name, $value, $force=false)
	Use to set the value of an option. More...

	getValue ( $name)
	Get the value for the given option name. More...

	reset ( $name)
	Delete the option value. More...

	consumeValue ( $name)
	Get the value of given option and mark it as 'consumed'. More...

	consumeValues ( $names)
	Get the values of given options and mark them as 'consumed'. More...

	validateIntBounds ( $name, $min, $max)

	validateBounds ( $name, $min, $max)
	Constrain a numeric value for a given option to a given range. More...

	getUnconsumedValues ( $all=false)
	Get all remaining values which have not been consumed by consumeValue() or consumeValues(). More...

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

	getAllValues ()
	Format options to an array ( name => value ) More...

	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. More...

static	guessType ( $data)
	Used to find out which type the data is. More...

	getValueReal ( $option)
	Return current option value, based on a structure taken from $options. More...

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 35 of file FormOptions.php.

Member Function Documentation

◆ add()

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 78 of file FormOptions.php.

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

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

◆ consumeValue()

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 214 of file FormOptions.php.

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

◆ consumeValues()

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 230 of file FormOptions.php.

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

◆ delete()

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 98 of file FormOptions.php.

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

◆ fetchValuesFromRequest()

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 336 of file FormOptions.php.

References $name, $type, $value, as, BOOL, FLOAT, WebRequest\getBool(), WebRequest\getFloat(), WebRequest\getInt(), WebRequest\getIntOrNull(), WebRequest\getText(), INT, INTNULL, options(), and STRING.

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

◆ getAllValues()

FormOptions::getAllValues ( )

Format options to an array ( name => value )

Returns: array

Definition at line 314 of file FormOptions.php.

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

◆ getChangedValues()

FormOptions::getChangedValues ( )

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

Returns: array

Definition at line 298 of file FormOptions.php.

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

Referenced by SpecialWatchlist\setTopText().

◆ getUnconsumedValues()

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 280 of file FormOptions.php.

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

◆ getValue()

FormOptions::getValue ( $name )

Get the value for the given option name.

Uses getValueReal() internally.

Parameters

string $name Option name

Returns: mixed

Definition at line 175 of file FormOptions.php.

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

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

◆ getValueReal()

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 187 of file FormOptions.php.

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

◆ guessType()

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 114 of file FormOptions.php.

References BOOL, FLOAT, INT, and STRING.

Referenced by add(), and FormOptionsTest\guess().

◆ offsetExists()

FormOptions::offsetExists ( $name )

Whether the option exists.

Returns: bool

Definition at line 380 of file FormOptions.php.

References $name, and options().

◆ offsetGet()

FormOptions::offsetGet ( $name )

Retrieve an option value.

Returns: mixed

Definition at line 388 of file FormOptions.php.

References $name, and getValue().

◆ offsetSet()

FormOptions::offsetSet	(	$name,
		$value
	)

Set an option to given value.

Definition at line 395 of file FormOptions.php.

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

◆ offsetUnset()

FormOptions::offsetUnset ( $name )

Delete the option.

Definition at line 402 of file FormOptions.php.

References $name.

◆ reset()

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 200 of file FormOptions.php.

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

Referenced by SpecialRecentChanges\buildMainQueryConds().

◆ setValue()

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 158 of file FormOptions.php.

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

Referenced by SpecialWhatLinksHere\execute(), offsetSet(), SpecialLog\parseParams(), SpecialNewpages\setup(), and validateBounds().

◆ validateBounds()

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

Constrain a numeric value for a given option to a given range.

The value will be altered to fit in the range.

Since: 1.23

Parameters

string	$name	Option name
int \| float	$min	Minimum value
int \| float	$max	Maximum value

Exceptions

MWException If option is not of type INT

Definition at line 260 of file FormOptions.php.

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

Referenced by validateIntBounds().

◆ validateIntBounds()

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

See also: validateBounds()

Definition at line 245 of file FormOptions.php.

References $name, and validateBounds().

Referenced by SpecialWhatLinksHere\execute(), SpecialNewpages\setup(), and SpecialRecentChanges\validateOptions().

◆ validateName()

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 138 of file FormOptions.php.

References $name, and options().

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

Member Data Documentation

◆ $options

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 67 of file FormOptions.php.

Referenced by FormOptionsExposed\getOptions().