diff options
Diffstat (limited to 'includes/FormOptions.php')
| -rw-r--r-- | includes/FormOptions.php | 163 |
1 files changed, 100 insertions, 63 deletions
diff --git a/includes/FormOptions.php b/includes/FormOptions.php index 8477ed98..54822e32 100644 --- a/includes/FormOptions.php +++ b/includes/FormOptions.php @@ -28,7 +28,8 @@ /** * Helper class to keep track of options when mixing links and form elements. * - * @todo This badly need some examples and tests :-) + * @todo This badly needs some examples and tests :) The usage in SpecialRecentchanges class is a + * good ersatz in the meantime. */ class FormOptions implements ArrayAccess { /** @name Type constants @@ -50,12 +51,26 @@ class FormOptions implements ArrayAccess { /* @} */ /** - * @todo Document! + * 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) */ protected $options = array(); # Setting up + /** + * Add an option to be handled by this FormOptions instance. + * + * @param string $name Request parameter name + * @param mixed $default Default value when the request parameter is not present + * @param int $type One of the type constants (optional, defaults to AUTO) + */ public function add( $name, $default, $type = self::AUTO ) { $option = array(); $option['default'] = $default; @@ -71,20 +86,25 @@ class FormOptions implements ArrayAccess { $this->options[$name] = $option; } + /** + * Remove an option being handled by this FormOptions instance. This is the inverse of add(). + * + * @param string $name Request parameter name + */ 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. + * Used to find out which type the data is. All types are defined in the 'Type constants' section + * of this class. * - * @param $data Mixed: value to guess type for - * @throws MWException - * @exception MWException Unsupported datatype + * 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. + * + * @param mixed $data Value to guess the type for + * @throws MWException If unable to guess the type * @return int Type constant */ public static function guessType( $data ) { @@ -102,12 +122,12 @@ class FormOptions implements ArrayAccess { # Handling values /** - * Verify the given option name exist. + * Verify that the given option name exists. * - * @param string $name option name - * @param $strict Boolean: throw an exception when the option does not exist (default false) + * @param string $name Option name + * @param bool $strict Throw an exception when the option doesn't exist instead of returning false * @throws MWException - * @return Boolean: true if option exist, false otherwise + * @return bool True if the option exists, false otherwise */ public function validateName( $name, $strict = false ) { if ( !isset( $this->options[$name] ) ) { @@ -117,16 +137,17 @@ class FormOptions implements ArrayAccess { return false; } } + return true; } /** * Use to set the value of an option. * - * @param string $name 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 + * @param string $name Option name + * @param mixed $value Value for the option + * @param bool $force Whether to set the value when it is equivalent to the default value for this + * option (default false). */ public function setValue( $name, $value, $force = false ) { $this->validateName( $name, true ); @@ -140,11 +161,10 @@ class FormOptions implements ArrayAccess { } /** - * Get the value for the given option name. - * Internally use getValueReal() + * Get the value for the given option name. Uses getValueReal() internally. * - * @param string $name option name - * @return Mixed + * @param string $name Option name + * @return mixed */ public function getValue( $name ) { $this->validateName( $name, true ); @@ -153,9 +173,10 @@ class FormOptions implements ArrayAccess { } /** - * @todo Document - * @param array $option array structure describing the option - * @return Mixed. Value or the default value if it is null + * Return current option value, based on a structure taken from $options. + * + * @param array $option Array structure describing the option + * @return mixed Value, or the default value if it is null */ protected function getValueReal( $option ) { if ( $option['value'] !== null ) { @@ -167,9 +188,8 @@ class FormOptions implements ArrayAccess { /** * Delete the option value. - * This will make future calls to getValue() return the default value. - * @param string $name option name - * @return null + * This will make future calls to getValue() return the default value. + * @param string $name Option name */ public function reset( $name ) { $this->validateName( $name, true ); @@ -177,10 +197,13 @@ class FormOptions implements ArrayAccess { } /** - * @todo Document + * Get the value of given option and mark it as 'consumed'. Consumed options are not returned + * by getUnconsumedValues(). + * + * @see consumeValues() + * @throws MWException If the option does not exist * @param string $name Option name - * @throws MWException If option does not exist. - * @return mixed Value or the default value if it is null. + * @return mixed Value, or the default value if it is null */ public function consumeValue( $name ) { $this->validateName( $name, true ); @@ -190,11 +213,15 @@ class FormOptions implements ArrayAccess { } /** - * @todo Document - * @param array $names array of option names - * @return null + * Get the values of given options and mark them as 'consumed'. Consumed options are not returned + * by getUnconsumedValues(). + * + * @see consumeValue() + * @throws MWException If any option does not exist + * @param array $names Array of option names as strings + * @return array Array of option values, or the default values if they are null */ - public function consumeValues( /*Array*/ $names ) { + public function consumeValues( $names ) { $out = array(); foreach ( $names as $name ) { @@ -213,9 +240,7 @@ class FormOptions implements ArrayAccess { * @param string $name option name * @param int $min minimum value * @param int $max maximum value - * @throws MWException - * @exception MWException Option is not of type int - * @return null + * @throws MWException If option is not of type INT */ public function validateIntBounds( $name, $min, $max ) { $this->validateName( $name, true ); @@ -231,9 +256,10 @@ class FormOptions implements ArrayAccess { } /** - * Getting the data out for use - * @param $all Boolean: whether to include unchanged options (default: false) - * @return Array + * Get all remaining values which have not been consumed by consumeValue() or consumeValues(). + * + * @param bool $all Whether to include unchanged options (default: false) + * @return array */ public function getUnconsumedValues( $all = false ) { $values = array(); @@ -251,7 +277,7 @@ class FormOptions implements ArrayAccess { /** * Return options modified as an array ( name => value ) - * @return Array + * @return array */ public function getChangedValues() { $values = array(); @@ -266,8 +292,8 @@ class FormOptions implements ArrayAccess { } /** - * Format options to an array ( name => value) - * @return Array + * Format options to an array ( name => value ) + * @return array */ public function getAllValues() { $values = array(); @@ -281,24 +307,38 @@ class FormOptions implements ArrayAccess { # Reading values - public function fetchValuesFromRequest( WebRequest $r, $values = false ) { - if ( !$values ) { - $values = array_keys( $this->options ); + /** + * Fetch values for all options (or selected options) from the given WebRequest, making them + * available for accessing with getValue() or consumeValue() etc. + * + * @param WebRequest $r The request to fetch values from + * @param 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. + * @throws MWException If the type of any option is invalid + */ + public function fetchValuesFromRequest( WebRequest $r, $optionKeys = null ) { + if ( !$optionKeys ) { + $optionKeys = array_keys( $this->options ); } - foreach ( $values as $name ) { + foreach ( $optionKeys as $name ) { $default = $this->options[$name]['default']; $type = $this->options[$name]['type']; - switch( $type ) { + switch ( $type ) { case self::BOOL: - $value = $r->getBool( $name, $default ); break; + $value = $r->getBool( $name, $default ); + break; case self::INT: - $value = $r->getInt( $name, $default ); break; + $value = $r->getInt( $name, $default ); + break; case self::STRING: - $value = $r->getText( $name, $default ); break; + $value = $r->getText( $name, $default ); + break; case self::INTNULL: - $value = $r->getIntOrNull( $name ); break; + $value = $r->getIntOrNull( $name ); + break; default: throw new MWException( 'Unsupported datatype' ); } @@ -310,29 +350,26 @@ class FormOptions implements ArrayAccess { } /** @name ArrayAccess functions - * Those function implements PHP ArrayAccess interface + * These functions implement the ArrayAccess PHP interface. * @see http://php.net/manual/en/class.arrayaccess.php */ /* @{ */ - /** - * Whether option exist - * @return bool - */ + /** Whether the option exists. */ public function offsetExists( $name ) { return isset( $this->options[$name] ); } - /** - * Retrieve an option value - * @return Mixed - */ + + /** Retrieve an option value. */ public function offsetGet( $name ) { return $this->getValue( $name ); } - /** Set an option to given value */ + + /** Set an option to given value. */ public function offsetSet( $name, $value ) { $this->setValue( $name, $value ); } - /** Delete the option */ + + /** Delete the option. */ public function offsetUnset( $name ) { $this->delete( $name ); } |