MediaWiki  1.34.0
FormOptions Class Reference

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
https://www.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...
 
const ARR = 5
 Array type, maps guessType() to WebRequest::getArray() More...
 
 $options = []
 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$nameRequest parameter name
mixed$defaultDefault value when the request parameter is not present
int$typeOne of the type constants (optional, defaults to AUTO)

Definition at line 83 of file FormOptions.php.

References $type, and guessType().

Referenced by ChangesListBooleanFilterGroup\addOptions(), ChangesListStringOptionsFilterGroup\addOptions(), SpecialNewFiles\execute(), SpecialLog\execute(), SpecialWhatLinksHere\execute(), 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
MWExceptionIf the option does not exist
Parameters
string$nameOption name
Returns
mixed Value, or the default value if it is null

Definition at line 221 of file FormOptions.php.

References getValueReal(), 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
MWExceptionIf any option does not exist
Parameters
array$namesArray of option names as strings
Returns
array Array of option values, or the default values if they are null

Definition at line 237 of file FormOptions.php.

References getValueReal(), and validateName().

◆ delete()

FormOptions::delete (   $name)

Remove an option being handled by this FormOptions instance.

This is the inverse of add().

Parameters
string$nameRequest parameter name

Definition at line 103 of file FormOptions.php.

References 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$rThe request to fetch values from
array | null$optionKeysWhich 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
MWExceptionIf the type of any option is invalid

Definition at line 346 of file FormOptions.php.

References $type, ARR, BOOL, FLOAT, WebRequest\getArray(), WebRequest\getBool(), WebRequest\getFloat(), WebRequest\getInt(), WebRequest\getIntOrNull(), WebRequest\getText(), INT, INTNULL, and STRING.

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

◆ getAllValues()

FormOptions::getAllValues ( )

Format options to an array ( name => value )

Returns
array

Definition at line 324 of file FormOptions.php.

References getValueReal().

◆ getChangedValues()

FormOptions::getChangedValues ( )

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

Returns
array

Definition at line 308 of file FormOptions.php.

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

◆ getUnconsumedValues()

FormOptions::getUnconsumedValues (   $all = false)

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

Parameters
bool$allWhether to include unchanged options (default: false)
Returns
array

Definition at line 290 of file FormOptions.php.

References getValueReal().

◆ getValue()

FormOptions::getValue (   $name)

Get the value for the given option name.

Uses getValueReal() internally.

Parameters
string$nameOption name
Returns
mixed

Definition at line 182 of file FormOptions.php.

References getValueReal(), and validateName().

Referenced by NewFilesPager\__construct(), ActiveUsersPager\__construct(), AllMessagesTablePager\__construct(), SpecialNewFiles\execute(), SpecialWhatLinksHere\execute(), NewFilesPager\getQueryInfo(), offsetGet(), and SpecialLog\show().

◆ getValueReal()

FormOptions::getValueReal (   $option)
protected

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

Parameters
array$optionArray structure describing the option
Returns
mixed Value, or the default value if it is null

Definition at line 194 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$dataValue to guess the type for
Exceptions
MWExceptionIf unable to guess the type
Returns
int Type constant

Definition at line 119 of file FormOptions.php.

References ARR, BOOL, FLOAT, INT, and STRING.

Referenced by add().

◆ offsetExists()

FormOptions::offsetExists (   $name)

Whether the option exists.

Parameters
string$name
Returns
bool

Definition at line 395 of file FormOptions.php.

◆ offsetGet()

FormOptions::offsetGet (   $name)

Retrieve an option value.

Parameters
string$name
Returns
mixed

Definition at line 404 of file FormOptions.php.

References getValue().

◆ offsetSet()

FormOptions::offsetSet (   $name,
  $value 
)

Set an option to given value.

Parameters
string$name
mixed$value

Definition at line 413 of file FormOptions.php.

References setValue().

◆ offsetUnset()

FormOptions::offsetUnset (   $name)

Delete the option.

Parameters
string$name

Definition at line 421 of file FormOptions.php.

◆ reset()

FormOptions::reset (   $name)

Delete the option value.

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

Parameters
string$nameOption name

Definition at line 207 of file FormOptions.php.

References validateName().

Referenced by ChangesListSpecialPage\buildQuery(), ChangesListSpecialPage\fixBackwardsCompatibilityOptions(), and ChangesListSpecialPage\replaceOldOptions().

◆ setValue()

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

Use to set the value of an option.

Parameters
string$nameOption name
mixed$valueValue for the option
bool$forceWhether to set the value when it is equivalent to the default value for this option (default false).

Definition at line 165 of file FormOptions.php.

References validateName().

Referenced by SpecialNewFiles\execute(), SpecialWhatLinksHere\execute(), offsetSet(), SpecialLog\parseParams(), 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$nameOption name
int | float$minMinimum value
int | float$maxMaximum value
Exceptions
MWExceptionIf option is not of type INT

Definition at line 270 of file FormOptions.php.

References $type, getValueReal(), setValue(), and validateName().

Referenced by validateIntBounds(), and ChangesListSpecialPage\validateOptions().

◆ validateIntBounds()

FormOptions::validateIntBounds (   $name,
  $min,
  $max 
)
See also
validateBounds()
Parameters
string$name
int$min
int$max

Definition at line 255 of file FormOptions.php.

References validateBounds().

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

◆ validateName()

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

Verify that the given option name exists.

Parameters
string$nameOption name
bool$strictThrow 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 145 of file FormOptions.php.

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

Member Data Documentation

◆ $options

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

◆ ARR

const FormOptions::ARR = 5

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

Since
1.29

Definition at line 59 of file FormOptions.php.

Referenced by fetchValuesFromRequest(), and guessType().

◆ AUTO

const FormOptions::AUTO = -1

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

Definition at line 41 of file FormOptions.php.

◆ BOOL

const FormOptions::BOOL = 2

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

Definition at line 51 of file FormOptions.php.

Referenced by SpecialActiveUsers\execute(), fetchValuesFromRequest(), and guessType().

◆ FLOAT

const FormOptions::FLOAT = 4

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

Since
1.23

Definition at line 49 of file FormOptions.php.

Referenced by fetchValuesFromRequest(), ChangesListSpecialPage\getDefaultOptions(), and guessType().

◆ INT

const FormOptions::INT = 1

◆ INTNULL

const FormOptions::INTNULL = 3

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

Definition at line 55 of file FormOptions.php.

Referenced by SpecialLog\execute(), SpecialWhatLinksHere\execute(), and fetchValuesFromRequest().

◆ STRING

const FormOptions::STRING = 0

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