From cb1b863ab1e59eb7aebb5c7de0123cbef37680a6 Mon Sep 17 00:00:00 2001
From: Antoine Musso <hashar@users.mediawiki.org>
Date: Mon, 28 Feb 2011 20:58:34 +0000
Subject: [PATCH] FormOptions: adds doc & tests

---
 includes/FormOptions.php                      | 121 ++++++++-
 .../FormOptionsInitializationTest.php         |  83 ++++++
 tests/phpunit/includes/FormOptionsTest.php    | 250 ++++++++++++++++++
 3 files changed, 442 insertions(+), 12 deletions(-)
 create mode 100644 tests/phpunit/includes/FormOptionsInitializationTest.php
 create mode 100644 tests/phpunit/includes/FormOptionsTest.php

diff --git a/includes/FormOptions.php b/includes/FormOptions.php
index 2442a33025..b668ff46ee 100644
--- a/includes/FormOptions.php
+++ b/includes/FormOptions.php
@@ -1,19 +1,38 @@
 <?php
 /**
  * Helper class to keep track of options when mixing links and form elements.
+ * @todo This badly need some examples and tests :-)
  *
- * Copyright © 2008, Niklas Laxström
+ * Copyright © 2008, Niklas Laxstiröm
+ *
+ * Copyright © 2011, Ashar Voultoiz
  *
  * @author Niklas Laxström
+ * @author Ashar Voultoiz 
  */
 
 class FormOptions implements ArrayAccess {
-	const AUTO = -1; // ! Automatically detects simple data types
+	/** @name Type constants
+	 * Used internally to map an option value to a WebRequest accessor
+	 */
+	/* @{ */
+	/** Mark value for automatic detection (for simple data types only) */
+	const AUTO = -1;
+	/** String type, maps guessType() to WebRequest::getText() */
 	const STRING = 0;
+	/** Integer type, maps guessType() to WebRequest::getInt() */
 	const INT = 1;
+	/** Boolean type, maps guessType() to WebRequest::getBool() */
 	const BOOL = 2;
-	const INTNULL = 3; // ! Useful for namespace selector
-
+	/** Integer type or null, maps to WebRequest::getIntOrNull()
+	 * This is useful for the namespace selector.
+	 */
+	const INTNULL = 3;
+	/* @} */
+
+	/**
+	 * @todo Document!
+	 */
 	protected $options = array();
 
 	# Setting up
@@ -38,6 +57,16 @@ class FormOptions implements ArrayAccess {
 		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.
+	 *
+	 * @param $data Mixed: value to guess type for
+	 * @exception MWException Unsupported datatype
+	 * @return Type constant 
+	 */
 	public static function guessType( $data ) {
 		if ( is_bool( $data ) ) {
 			return self::BOOL;
@@ -52,6 +81,13 @@ class FormOptions implements ArrayAccess {
 
 	# Handling values
 
+	/**
+	 * Verify the given option name exist.
+	 *
+	 * @param $name String: option name
+	 * @param $strict Boolean: throw an exception when the option does not exist (default false)
+	 * @return Boolean: true if option exist, false otherwise
+	 */
 	public function validateName( $name, $strict = false ) {
 		if ( !isset( $this->options[$name] ) ) {
 			if ( $strict ) {
@@ -63,6 +99,14 @@ class FormOptions implements ArrayAccess {
 		return true;
 	}
 
+	/**
+	 * Use to set the value of an option.
+	 *
+	 * @param $name String: 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
+	 */
 	public function setValue( $name, $value, $force = false ) {
 		$this->validateName( $name, true );
 
@@ -74,12 +118,24 @@ class FormOptions implements ArrayAccess {
 		}
 	}
 
+	/**
+	 * Get the value for the given option name.
+	 * Internally use getValueReal()
+	 *
+	 * @param $name String: option name
+	 * @return Mixed
+	 */
 	public function getValue( $name ) {
 		$this->validateName( $name, true );
 
 		return $this->getValueReal( $this->options[$name] );
 	}
 
+	/**
+	 * @todo Document
+	 * @param $option Array: array structure describing the option
+	 * @return Mixed. Value or the default value if it is null
+	 */
 	protected function getValueReal( $option ) {
 		if ( $option['value'] !== null ) {
 			return $option['value'];
@@ -88,11 +144,22 @@ class FormOptions implements ArrayAccess {
 		}
 	}
 
+	/**
+	 * Delete the option value.
+	 * This will make future calls to getValue()  return the default value.
+	 * @param $name String: option name
+	 * @return null
+	 */
 	public function reset( $name ) {
 		$this->validateName( $name, true );
 		$this->options[$name]['value'] = null;
 	}
 
+	/**
+	 * @todo Document
+	 * @param $name String: option name
+	 * @return null
+	 */
 	public function consumeValue( $name ) {
 		$this->validateName( $name, true );
 		$this->options[$name]['consumed'] = true;
@@ -100,6 +167,11 @@ class FormOptions implements ArrayAccess {
 		return $this->getValueReal( $this->options[$name] );
 	}
 
+	/**
+	 * @todo Document
+	 * @param $names Array: array of option names
+	 * @return null
+	 */
 	public function consumeValues( /*Array*/ $names ) {
 		$out = array();
 
@@ -112,8 +184,16 @@ class FormOptions implements ArrayAccess {
 		return $out;
 	}
 
-	# Validating values
-
+	/**
+	 * Validate and set an option integer value
+	 * The value will be altered to fit in the range. 
+	 *
+	 * @param $name String: option name
+	 * @param $min Int: minimum value
+	 * @param $max Int: maximum value
+	 * @exception MWException Option is not of type int
+	 * @return null
+	 */
 	public function validateIntBounds( $name, $min, $max ) {
 		$this->validateName( $name, true );
 
@@ -127,8 +207,11 @@ class FormOptions implements ArrayAccess {
 		$this->setValue( $name, $value );
 	}
 
-	# Getting the data out for use
-
+	/**
+	 * Getting the data out for use
+	 * @param $all Boolean: whether to include unchanged options (default: false)
+	 * @return Array
+	 */
 	public function getUnconsumedValues( $all = false ) {
 		$values = array();
 
@@ -143,6 +226,10 @@ class FormOptions implements ArrayAccess {
 		return $values;
 	}
 
+	/**
+	 * Return options modified as an array ( name => value )
+	 * @return Array
+	 */
 	public function getChangedValues() {
 		$values = array();
 
@@ -155,6 +242,10 @@ class FormOptions implements ArrayAccess {
 		return $values;
 	}
 
+	/**
+	 * Format options to an array ( name => value)
+	 * @return Array
+	 */
 	public function getAllValues() {
 		$values = array();
 
@@ -195,20 +286,26 @@ class FormOptions implements ArrayAccess {
 		}
 	}
 
-	/* ArrayAccess methods */
+	/** @name ArrayAccess functions
+	 * Those function implements PHP ArrayAccess interface
+	 * @see http://php.net/manual/en/class.arrayaccess.php
+	 */
+	/* @{ */
+	/** Whether option exist*/
 	public function offsetExists( $name ) {
 		return isset( $this->options[$name] );
 	}
-
+	/** Retrieve an option value */
 	public function offsetGet( $name ) {
 		return $this->getValue( $name );
 	}
-
+	/**	Set an option to given value */
 	public function offsetSet( $name, $value ) {
 		$this->setValue( $name, $value );
 	}
-
+	/**	Delete the option */
 	public function offsetUnset( $name ) {
 		$this->delete( $name );
 	}
+	/* @} */
 }
diff --git a/tests/phpunit/includes/FormOptionsInitializationTest.php b/tests/phpunit/includes/FormOptionsInitializationTest.php
new file mode 100644
index 0000000000..b2f7fdb4d4
--- /dev/null
+++ b/tests/phpunit/includes/FormOptionsInitializationTest.php
@@ -0,0 +1,83 @@
+<?php
+/**
+ * This file host two test case classes for the MediaWiki FormOptions class:
+ *  - FormOptionsInitializationTest : tests initialization of the class.
+ *  - FormOptionsTest : tests methods an on instance
+ *
+ * The split let us take advantage of setting up a fixture for the methods
+ * tests.
+ */
+
+/**
+ * Dummy class to makes FormOptions::$options public.
+ * Used by FormOptionsInitializationTest which need to verify the $options
+ * array is correctly set through the FormOptions::add() function.
+ */
+class FormOptionsExposed extends FormOptions {
+	public $options;
+}
+
+/**
+ * Test class for FormOptions initialization
+ * Ensure the FormOptions::add() does what we want it to do.
+ *
+ * Generated by PHPUnit on 2011-02-28 at 20:46:27.
+ *
+ * Copyright © 2011, Ashar Voultoiz
+ *
+ * @author Ashar Voultoiz
+ */
+class FormOptionsInitializationTest extends MediaWikiTestCase {
+	/**
+	 * @var FormOptions
+	 */
+	protected $object;
+
+
+	/**
+	 * A new fresh and empty FormOptions object to test initialization
+	 * with.
+	 */
+	protected function setUp() {
+		$this->object = new FormOptionsExposed();
+		
+	}
+
+	public function testAddStringOption() {
+		$this->object->add( 'foo', 'string value' ); 
+		$this->assertEquals(
+			array(
+				'foo' => array(
+					'default'  => 'string value',
+					'consumed' => false,
+					'type'	 => FormOptions::STRING,
+					'value'	=> null,
+					)
+			),
+			$this->object->options
+		);
+	}
+
+	public function testAddIntegers() {
+		$this->object->add( 'one',     1 ); 
+		$this->object->add( 'negone', -1 ); 
+		$this->assertEquals(
+			array(
+				'negone' => array(
+					'default'  => -1, 
+					'value'	=> null,
+					'consumed' => false,
+					'type'	 => FormOptions::INT,
+					),
+				'one' => array(
+					'default'  => 1,
+					'value'	=> null,
+					'consumed' => false,
+					'type'	 => FormOptions::INT,
+					)
+			),
+			$this->object->options
+		);
+	}
+
+}
diff --git a/tests/phpunit/includes/FormOptionsTest.php b/tests/phpunit/includes/FormOptionsTest.php
new file mode 100644
index 0000000000..eab2def3f4
--- /dev/null
+++ b/tests/phpunit/includes/FormOptionsTest.php
@@ -0,0 +1,250 @@
+<?php
+/**
+ * This file host two test case classes for the MediaWiki FormOptions class:
+ *  - FormOptionsInitializationTest : tests initialization of the class.
+ *  - FormOptionsTest : tests methods an on instance
+ *
+ * The split let us take advantage of setting up a fixture for the methods
+ * tests.
+ */
+
+/**
+ * Test class for FormOptions methods.
+ * Generated by PHPUnit on 2011-02-28 at 20:46:27.
+ *
+ * Copyright © 2011, Ashar Voultoiz
+ *
+ * @author Ashar Voultoiz
+ */
+class FormOptionsTest extends MediaWikiTestCase {
+	/**
+	 * @var FormOptions
+	 */
+	protected $object;
+
+	/**
+	 * Instanciates a FormOptions object to play with.	 
+	 * FormOptions::add() is tested by the class FormOptionsInitializationTest
+	 * so we assume the function is well tested already an use it to create
+	 * the fixture.
+	 */
+	protected function setUp() {
+		$this->object = new FormOptions;
+		$this->object->add( 'string1', 'string one' );
+		$this->object->add( 'string2', 'string two' );
+		$this->object->add( 'integer',  0 );
+		$this->object->add( 'intnull',  0, FormOptions::INTNULL );
+	}
+
+	/**
+	 * @todo Implement testDelete().
+	 */
+	public function testDelete() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/** Helpers for testGuessType() */
+	/* @{ */
+	private function assertGuessBoolean( $data ) {
+		$this->guess( FormOptions::BOOL, $data );
+	}
+	private function assertGuessInt( $data ) {
+		$this->guess( FormOptions::INT, $data );
+	}
+	private function assertGuessString( $data ) {
+		$this->guess( FormOptions::STRING, $data );
+	}
+
+	/** Generic helper */
+	private function guess( $expected, $data ) {
+		$this->assertEquals(
+			$expected,
+			FormOptions::guessType( $data )
+		);
+	}
+	/* @} */
+
+	/**
+	 * Reuse helpers above assertGuessBoolean assertGuessInt assertGuessString
+	 */
+	public function testGuessTypeDetection() {
+		$this->assertGuessBoolean( true  );
+		$this->assertGuessBoolean( false );
+
+		$this->assertGuessInt(    0 );
+		$this->assertGuessInt(   -5 );
+		$this->assertGuessInt(    5 );
+		$this->assertGuessInt( 0x0F );
+
+		$this->assertGuessString( 'true'  );
+		$this->assertGuessString( 'false' ); 
+		$this->assertGuessString( '5'     ); 
+		$this->assertGuessString( '0'     ); 
+	}
+
+	/**
+	 * @expectedException MWException 
+	 */
+	public function testGuessTypeOnArrayThrowException() {
+		$this->object->guessType( array( 'foo' ) ); 
+	}
+	/**
+	 * @expectedException MWException 
+	 */
+	public function testGuessTypeOnNullThrowException() {
+		$this->object->guessType( null ); 
+	}
+
+	/**
+	 * @todo Implement testValidateName().
+	 */
+	public function testValidateName() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testSetValue().
+	 */
+	public function testSetValue() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testGetValue().
+	 */
+	public function testGetValue() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testReset().
+	 */
+	public function testReset() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testConsumeValue().
+	 */
+	public function testConsumeValue() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testConsumeValues().
+	 */
+	public function testConsumeValues() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testValidateIntBounds().
+	 */
+	public function testValidateIntBounds() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testGetUnconsumedValues().
+	 */
+	public function testGetUnconsumedValues() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testGetChangedValues().
+	 */
+	public function testGetChangedValues() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testGetAllValues().
+	 */
+	public function testGetAllValues() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testFetchValuesFromRequest().
+	 */
+	public function testFetchValuesFromRequest() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testOffsetExists().
+	 */
+	public function testOffsetExists() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testOffsetGet().
+	 */
+	public function testOffsetGet() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testOffsetSet().
+	 */
+	public function testOffsetSet() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+
+	/**
+	 * @todo Implement testOffsetUnset().
+	 */
+	public function testOffsetUnset() {
+		// Remove the following lines when you implement this test.
+		$this->markTestIncomplete(
+		  'This test has not been implemented yet.'
+		);
+	}
+}
-- 
2.20.1