<?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
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;
# 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 ) {
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 );
}
}
+ /**
+ * 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'];
}
}
+ /**
+ * 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;
return $this->getValueReal( $this->options[$name] );
}
+ /**
+ * @todo Document
+ * @param $names Array: array of option names
+ * @return null
+ */
public function consumeValues( /*Array*/ $names ) {
$out = array();
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 );
$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();
return $values;
}
+ /**
+ * Return options modified as an array ( name => value )
+ * @return Array
+ */
public function getChangedValues() {
$values = array();
return $values;
}
+ /**
+ * Format options to an array ( name => value)
+ * @return Array
+ */
public function getAllValues() {
$values = array();
}
}
- /* 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 );
}
+ /* @} */
}
--- /dev/null
+<?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
+ );
+ }
+
+}
--- /dev/null
+<?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.'
+ );
+ }
+}
dépôts / lhc / web / wiklou.git / commitdiff