Bartosz Dziewoński has uploaded a new change for review.
https://gerrit.wikimedia.org/r/89403
Change subject: FormOptions: More documentation!
......................................................................
FormOptions: More documentation!
Change-Id: I088b07c1672426c45d995fdf96ac7fc7bda21307
---
M includes/FormOptions.php
1 file changed, 77 insertions(+), 48 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core
refs/changes/03/89403/1
diff --git a/includes/FormOptions.php b/includes/FormOptions.php
index 530b094..a3eaf51 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,25 @@
/* @} */
/**
- * @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,21 +85,26 @@
$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
- * @return int Type constant
+ * 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 ) {
if ( is_bool( $data ) ) {
@@ -102,12 +121,12 @@
# 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] ) ) {
@@ -124,9 +143,8 @@
* Use to set the value of an option.
*
* @param string $name option name
- * @param $value Mixed: value for the option
+ * @param mixed $value 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
*/
public function setValue( $name, $value, $force = false ) {
$this->validateName( $name, true );
@@ -167,9 +185,8 @@
/**
* 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 +194,13 @@
}
/**
- * @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 +210,15 @@
}
/**
- * @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 +237,7 @@
* @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 +253,10 @@
}
/**
- * 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();
@@ -266,7 +289,7 @@
}
/**
- * Format options to an array ( name => value)
+ * Format options to an array ( name => value )
* @return Array
*/
public function getAllValues() {
@@ -281,12 +304,21 @@
# 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'];
@@ -314,29 +346,26 @@
}
/** @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 );
}
--
To view, visit https://gerrit.wikimedia.org/r/89403
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I088b07c1672426c45d995fdf96ac7fc7bda21307
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Bartosz Dziewoński <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
