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

Inherits ArrayAccess.

Collaboration diagram for MediaWiki\Html\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.

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

	validateIntBounds ( $name, $min, $max)

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

ArrayAccess functions
These functions implement the ArrayAccess PHP interface. See also https://www.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	FLOAT = 4
	Float type, maps guessType() to WebRequest::getFloat()

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.

const	ARR = 5
	Array type, maps guessType() to WebRequest::getArray()

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

Protected Attributes
	$options = []
	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 42 of file FormOptions.php.

Member Function Documentation

◆ add()

MediaWiki\Html\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 90 of file FormOptions.php.

References MediaWiki\Html\FormOptions\guessType().

Referenced by ChangesListBooleanFilterGroup\addOptions(), ChangesListStringOptionsFilterGroup\addOptions(), MediaWiki\Specials\SpecialLog\execute(), MediaWiki\Specials\SpecialNewFiles\execute(), MediaWiki\Specials\SpecialWhatLinksHere\onSuccess(), and MediaWiki\Specials\SpecialNewPages\setup().

◆ consumeValue()

MediaWiki\Html\FormOptions::consumeValue ( $name )

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

Consumed options are not returned by getUnconsumedValues(). Callers should verify that the given option exists.

See also: consumeValues()

Parameters

string $name Option name

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

Definition at line 226 of file FormOptions.php.

References MediaWiki\Html\FormOptions\getValueReal(), and MediaWiki\Html\FormOptions\validateName().

◆ consumeValues()

MediaWiki\Html\FormOptions::consumeValues ( $names )

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

Consumed options are not returned by getUnconsumedValues(). Callers should verify that all the given options exist.

See also: consumeValue()

Parameters

string[] $names List of option names

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

Definition at line 241 of file FormOptions.php.

References MediaWiki\Html\FormOptions\getValueReal(), and MediaWiki\Html\FormOptions\validateName().

◆ delete()

MediaWiki\Html\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 110 of file FormOptions.php.

References MediaWiki\Html\FormOptions\validateName().

◆ fetchValuesFromRequest()

MediaWiki\Html\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 \| null	$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.

Definition at line 348 of file FormOptions.php.

References MediaWiki\Html\FormOptions\ARR, MediaWiki\Html\FormOptions\BOOL, MediaWiki\Html\FormOptions\FLOAT, MediaWiki\Request\WebRequest\getArray(), MediaWiki\Request\WebRequest\getBool(), MediaWiki\Request\WebRequest\getFloat(), MediaWiki\Request\WebRequest\getInt(), MediaWiki\Request\WebRequest\getIntOrNull(), MediaWiki\Request\WebRequest\getText(), MediaWiki\Html\FormOptions\INT, MediaWiki\Html\FormOptions\INTNULL, and MediaWiki\Html\FormOptions\STRING.

Referenced by MediaWiki\Specials\SpecialNewFiles\execute(), MediaWiki\Specials\SpecialWhatLinksHere\onSuccess(), and MediaWiki\Specials\SpecialNewPages\setup().

◆ getAllValues()

MediaWiki\Html\FormOptions::getAllValues ( )

Format options to an array ( name => value )

Returns: array

Definition at line 327 of file FormOptions.php.

References MediaWiki\Html\FormOptions\getValueReal().

◆ getChangedValues()

MediaWiki\Html\FormOptions::getChangedValues ( )

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

Returns: array

Definition at line 311 of file FormOptions.php.

Referenced by MediaWiki\Specials\SpecialWatchlist\setTopText(), and MediaWiki\SpecialPage\ChangesListSpecialPage\validateOptions().

◆ getUnconsumedValues()

MediaWiki\Html\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 293 of file FormOptions.php.

References MediaWiki\Html\FormOptions\getValueReal().

◆ getValue()

MediaWiki\Html\FormOptions::getValue ( $name )

Get the value for the given option name.

Uses getValueReal() internally.

Parameters

string $name Option name

Returns: mixed

statically.

Definition at line 188 of file FormOptions.php.

References MediaWiki\Html\FormOptions\getValueReal(), and MediaWiki\Html\FormOptions\validateName().

Referenced by MediaWiki\Pager\NewFilesPager\__construct(), MediaWiki\Pager\ActiveUsersPager\__construct(), MediaWiki\Pager\AllMessagesTablePager\__construct(), MediaWiki\Specials\SpecialNewFiles\execute(), MediaWiki\Pager\NewFilesPager\getQueryInfo(), and MediaWiki\Specials\SpecialWhatLinksHere\onSuccess().

◆ getValueReal()

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

Referenced by MediaWiki\Html\FormOptions\consumeValue(), MediaWiki\Html\FormOptions\consumeValues(), MediaWiki\Html\FormOptions\getAllValues(), MediaWiki\Html\FormOptions\getUnconsumedValues(), MediaWiki\Html\FormOptions\getValue(), and MediaWiki\Html\FormOptions\validateBounds().

◆ guessType()

static MediaWiki\Html\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.

Parameters

mixed $data Value to guess the type for

Returns: int Type constant

Definition at line 124 of file FormOptions.php.

References MediaWiki\Html\FormOptions\ARR, MediaWiki\Html\FormOptions\BOOL, MediaWiki\Html\FormOptions\FLOAT, MediaWiki\Html\FormOptions\INT, and MediaWiki\Html\FormOptions\STRING.

Referenced by MediaWiki\Html\FormOptions\add().

◆ offsetExists()

MediaWiki\Html\FormOptions::offsetExists ( $name )

Whether the option exists.

Parameters

string $name

Returns: bool

Definition at line 403 of file FormOptions.php.

◆ offsetGet()

MediaWiki\Html\FormOptions::offsetGet ( $name )

Retrieve an option value.

Parameters

string $name

Returns: mixed

Definition at line 413 of file FormOptions.php.

◆ offsetSet()

MediaWiki\Html\FormOptions::offsetSet	(		$name,
			$value )

Set an option to given value.

Parameters

string	$name
mixed	$value

Definition at line 422 of file FormOptions.php.

◆ offsetUnset()

MediaWiki\Html\FormOptions::offsetUnset ( $name )

Delete the option.

Parameters

string $name

Definition at line 430 of file FormOptions.php.

◆ reset()

MediaWiki\Html\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 213 of file FormOptions.php.

References MediaWiki\Html\FormOptions\validateName().

Referenced by MediaWiki\SpecialPage\ChangesListSpecialPage\buildQuery(), and MediaWiki\SpecialPage\ChangesListSpecialPage\replaceOldOptions().

◆ setValue()

MediaWiki\Html\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 169 of file FormOptions.php.

References MediaWiki\Html\FormOptions\validateName().

Referenced by MediaWiki\Specials\SpecialNewFiles\execute(), MediaWiki\Specials\SpecialWhatLinksHere\onSuccess(), and MediaWiki\Html\FormOptions\validateBounds().

◆ validateBounds()

MediaWiki\Html\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. Must be of numeric type.
int \| float	$min	Minimum value
int \| float	$max	Maximum value

Definition at line 273 of file FormOptions.php.

References MediaWiki\Html\FormOptions\getValueReal(), MediaWiki\Html\FormOptions\setValue(), and MediaWiki\Html\FormOptions\validateName().

Referenced by MediaWiki\Html\FormOptions\validateIntBounds(), and MediaWiki\SpecialPage\ChangesListSpecialPage\validateOptions().

◆ validateIntBounds()

MediaWiki\Html\FormOptions::validateIntBounds	(	$name,
		$min,
		$max )

See also: validateBounds()

Parameters

string	$name
int	$min
int	$max

Definition at line 259 of file FormOptions.php.

References MediaWiki\Html\FormOptions\validateBounds().

Referenced by MediaWiki\Specials\SpecialNewFiles\execute(), MediaWiki\Specials\SpecialWhatLinksHere\onSuccess(), MediaWiki\Specials\SpecialNewPages\setup(), and MediaWiki\SpecialPage\ChangesListSpecialPage\validateOptions().

◆ validateName()

MediaWiki\Html\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

Returns: bool True if the option exists, false otherwise

Definition at line 149 of file FormOptions.php.

Referenced by MediaWiki\Html\FormOptions\consumeValue(), MediaWiki\Html\FormOptions\consumeValues(), MediaWiki\Html\FormOptions\delete(), MediaWiki\Html\FormOptions\getValue(), MediaWiki\Html\FormOptions\reset(), MediaWiki\Html\FormOptions\setValue(), and MediaWiki\Html\FormOptions\validateBounds().

Member Data Documentation

◆ $options

MediaWiki\Html\FormOptions::$options = []

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

◆ ARR

const MediaWiki\Html\FormOptions::ARR = 5

Array type, maps guessType() to WebRequest::getArray()

Since: 1.29

Definition at line 66 of file FormOptions.php.

Referenced by MediaWiki\Html\FormOptions\fetchValuesFromRequest(), and MediaWiki\Html\FormOptions\guessType().

◆ AUTO

const MediaWiki\Html\FormOptions::AUTO = -1

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

Definition at line 48 of file FormOptions.php.

◆ BOOL

const MediaWiki\Html\FormOptions::BOOL = 2

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

Definition at line 58 of file FormOptions.php.

Referenced by MediaWiki\Html\FormOptions\fetchValuesFromRequest(), and MediaWiki\Html\FormOptions\guessType().

◆ FLOAT

const MediaWiki\Html\FormOptions::FLOAT = 4

Float type, maps guessType() to WebRequest::getFloat()

Since: 1.23

Definition at line 56 of file FormOptions.php.

Referenced by MediaWiki\Html\FormOptions\fetchValuesFromRequest(), and MediaWiki\Html\FormOptions\guessType().

◆ INT

const MediaWiki\Html\FormOptions::INT = 1

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

Definition at line 52 of file FormOptions.php.

Referenced by MediaWiki\Html\FormOptions\fetchValuesFromRequest(), and MediaWiki\Html\FormOptions\guessType().

◆ INTNULL

const MediaWiki\Html\FormOptions::INTNULL = 3

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

Definition at line 62 of file FormOptions.php.

Referenced by MediaWiki\Html\FormOptions\fetchValuesFromRequest().

◆ STRING

const MediaWiki\Html\FormOptions::STRING = 0

String type, maps guessType() to WebRequest::getText()

Definition at line 50 of file FormOptions.php.

Referenced by MediaWiki\Html\FormOptions\fetchValuesFromRequest(), and MediaWiki\Html\FormOptions\guessType().

The documentation for this class was generated from the following file:

includes/Html/FormOptions.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ add()

◆ consumeValue()

◆ consumeValues()

◆ delete()

◆ fetchValuesFromRequest()

◆ getAllValues()

◆ getChangedValues()

◆ getUnconsumedValues()

◆ getValue()

◆ getValueReal()

◆ guessType()

◆ offsetExists()

◆ offsetGet()

◆ offsetSet()

◆ offsetUnset()

◆ reset()

◆ setValue()

◆ validateBounds()

◆ validateIntBounds()

◆ validateName()

Member Data Documentation

◆ $options

◆ ARR

◆ AUTO

◆ BOOL

◆ FLOAT

◆ INT

◆ INTNULL

◆ STRING