includes/FormOptions.php

   1 <?php
   2 /**
   3  * Helper class to keep track of options when mixing links and form elements.
   4  *
   5  * Copyright © 2008, Niklas Laxström
   6  * Copyright © 2011, Antoine Musso
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License along
  19  * with this program; if not, write to the Free Software Foundation, Inc.,
  20  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  21  * http://www.gnu.org/copyleft/gpl.html
  22  *
  23  * @file
  24  * @author Niklas Laxström
  25  * @author Antoine Musso
  26  */
  27
  28 /**
  29  * Helper class to keep track of options when mixing links and form elements.
  30  *
  31  * @todo This badly need some examples and tests :-)
  32  */
  33 class FormOptions implements ArrayAccess {
  34         /** @name Type constants
  35          * Used internally to map an option value to a WebRequest accessor
  36          */
  37         /* @{ */
  38         /** Mark value for automatic detection (for simple data types only) */
  39         const AUTO = -1;
  40         /** String type, maps guessType() to WebRequest::getText() */
  41         const STRING = 0;
  42         /** Integer type, maps guessType() to WebRequest::getInt() */
  43         const INT = 1;
  44         /** Boolean type, maps guessType() to WebRequest::getBool() */
  45         const BOOL = 2;
  46         /** Integer type or null, maps to WebRequest::getIntOrNull()
  47          * This is useful for the namespace selector.
  48          */
  49         const INTNULL = 3;
  50         /* @} */
  51
  52         /**
  53          * @todo Document!
  54          */
  55         protected $options = array();
  56
  57         # Setting up
  58
  59         public function add( $name, $default, $type = self::AUTO ) {
  60                 $option = array();
  61                 $option['default'] = $default;
  62                 $option['value'] = null;
  63                 $option['consumed'] = false;
  64
  65                 if ( $type !== self::AUTO ) {
  66                         $option['type'] = $type;
  67                 } else {
  68                         $option['type'] = self::guessType( $default );
  69                 }
  70
  71                 $this->options[$name] = $option;
  72         }
  73
  74         public function delete( $name ) {
  75                 $this->validateName( $name, true );
  76                 unset( $this->options[$name] );
  77         }
  78
  79         /**
  80          * Used to find out which type the data is.
  81          * All types are defined in the 'Type constants' section of this class
  82          * Please note we do not support detection of INTNULL MediaWiki type
  83          * which will be assumed as INT if the data is an integer.
  84          *
  85          * @param $data Mixed: value to guess type for
  86          * @throws MWException
  87          * @exception MWException Unsupported datatype
  88          * @return int Type constant
  89          */
  90         public static function guessType( $data ) {
  91                 if ( is_bool( $data ) ) {
  92                         return self::BOOL;
  93                 } elseif ( is_int( $data ) ) {
  94                         return self::INT;
  95                 } elseif ( is_string( $data ) ) {
  96                         return self::STRING;
  97                 } else {
  98                         throw new MWException( 'Unsupported datatype' );
  99                 }
 100         }
 101
 102         # Handling values
 103
 104         /**
 105          * Verify the given option name exist.
 106          *
 107          * @param string $name option name
 108          * @param $strict Boolean: throw an exception when the option does not exist (default false)
 109          * @throws MWException
 110          * @return Boolean: true if option exist, false otherwise
 111          */
 112         public function validateName( $name, $strict = false ) {
 113                 if ( !isset( $this->options[$name] ) ) {
 114                         if ( $strict ) {
 115                                 throw new MWException( "Invalid option $name" );
 116                         } else {
 117                                 return false;
 118                         }
 119                 }
 120                 return true;
 121         }
 122
 123         /**
 124          * Use to set the value of an option.
 125          *
 126          * @param string $name option name
 127          * @param $value Mixed: value for the option
 128          * @param $force Boolean: whether to set the value when it is equivalent to the default value for this option (default false).
 129          * @return null
 130          */
 131         public function setValue( $name, $value, $force = false ) {
 132                 $this->validateName( $name, true );
 133
 134                 if ( !$force && $value === $this->options[$name]['default'] ) {
 135                         // null default values as unchanged
 136                         $this->options[$name]['value'] = null;
 137                 } else {
 138                         $this->options[$name]['value'] = $value;
 139                 }
 140         }
 141
 142         /**
 143          * Get the value for the given option name.
 144          * Internally use getValueReal()
 145          *
 146          * @param string $name option name
 147          * @return Mixed
 148          */
 149         public function getValue( $name ) {
 150                 $this->validateName( $name, true );
 151
 152                 return $this->getValueReal( $this->options[$name] );
 153         }
 154
 155         /**
 156          * @todo Document
 157          * @param array $option array structure describing the option
 158          * @return Mixed. Value or the default value if it is null
 159          */
 160         protected function getValueReal( $option ) {
 161                 if ( $option['value'] !== null ) {
 162                         return $option['value'];
 163                 } else {
 164                         return $option['default'];
 165                 }
 166         }
 167
 168         /**
 169          * Delete the option value.
 170          * This will make future calls to getValue()  return the default value.
 171          * @param string $name option name
 172          * @return null
 173          */
 174         public function reset( $name ) {
 175                 $this->validateName( $name, true );
 176                 $this->options[$name]['value'] = null;
 177         }
 178
 179         /**
 180          * @todo Document
 181          * @param string $name Option name
 182          * @throws MWException If option does not exist.
 183          * @return mixed Value or the default value if it is null.
 184          */
 185         public function consumeValue( $name ) {
 186                 $this->validateName( $name, true );
 187                 $this->options[$name]['consumed'] = true;
 188
 189                 return $this->getValueReal( $this->options[$name] );
 190         }
 191
 192         /**
 193          * @todo Document
 194          * @param array $names array of option names
 195          * @return null
 196          */
 197         public function consumeValues( /*Array*/ $names ) {
 198                 $out = array();
 199
 200                 foreach ( $names as $name ) {
 201                         $this->validateName( $name, true );
 202                         $this->options[$name]['consumed'] = true;
 203                         $out[] = $this->getValueReal( $this->options[$name] );
 204                 }
 205
 206                 return $out;
 207         }
 208
 209         /**
 210          * Validate and set an option integer value
 211          * The value will be altered to fit in the range.
 212          *
 213          * @param string $name option name
 214          * @param int $min minimum value
 215          * @param int $max maximum value
 216          * @throws MWException
 217          * @exception MWException Option is not of type int
 218          * @return null
 219          */
 220         public function validateIntBounds( $name, $min, $max ) {
 221                 $this->validateName( $name, true );
 222
 223                 if ( $this->options[$name]['type'] !== self::INT ) {
 224                         throw new MWException( "Option $name is not of type int" );
 225                 }
 226
 227                 $value = $this->getValueReal( $this->options[$name] );
 228                 $value = max( $min, min( $max, $value ) );
 229
 230                 $this->setValue( $name, $value );
 231         }
 232
 233         /**
 234          * Getting the data out for use
 235          * @param $all Boolean: whether to include unchanged options (default: false)
 236          * @return Array
 237          */
 238         public function getUnconsumedValues( $all = false ) {
 239                 $values = array();
 240
 241                 foreach ( $this->options as $name => $data ) {
 242                         if ( !$data['consumed'] ) {
 243                                 if ( $all || $data['value'] !== null ) {
 244                                         $values[$name] = $this->getValueReal( $data );
 245                                 }
 246                         }
 247                 }
 248
 249                 return $values;
 250         }
 251
 252         /**
 253          * Return options modified as an array ( name => value )
 254          * @return Array
 255          */
 256         public function getChangedValues() {
 257                 $values = array();
 258
 259                 foreach ( $this->options as $name => $data ) {
 260                         if ( $data['value'] !== null ) {
 261                                 $values[$name] = $data['value'];
 262                         }
 263                 }
 264
 265                 return $values;
 266         }
 267
 268         /**
 269          * Format options to an array ( name => value)
 270          * @return Array
 271          */
 272         public function getAllValues() {
 273                 $values = array();
 274
 275                 foreach ( $this->options as $name => $data ) {
 276                         $values[$name] = $this->getValueReal( $data );
 277                 }
 278
 279                 return $values;
 280         }
 281
 282         # Reading values
 283
 284         public function fetchValuesFromRequest( WebRequest $r, $values = false ) {
 285                 if ( !$values ) {
 286                         $values = array_keys( $this->options );
 287                 }
 288
 289                 foreach ( $values as $name ) {
 290                         $default = $this->options[$name]['default'];
 291                         $type = $this->options[$name]['type'];
 292
 293                         switch ( $type ) {
 294                                 case self::BOOL:
 295                                         $value = $r->getBool( $name, $default );
 296                                         break;
 297                                 case self::INT:
 298                                         $value = $r->getInt( $name, $default );
 299                                         break;
 300                                 case self::STRING:
 301                                         $value = $r->getText( $name, $default );
 302                                         break;
 303                                 case self::INTNULL:
 304                                         $value = $r->getIntOrNull( $name );
 305                                         break;
 306                                 default:
 307                                         throw new MWException( 'Unsupported datatype' );
 308                         }
 309
 310                         if ( $value !== null ) {
 311                                 $this->options[$name]['value'] = $value === $default ? null : $value;
 312                         }
 313                 }
 314         }
 315
 316         /** @name ArrayAccess functions
 317          * Those function implements PHP ArrayAccess interface
 318          * @see http://php.net/manual/en/class.arrayaccess.php
 319          */
 320         /* @{ */
 321         /**
 322          * Whether option exist
 323          * @return bool
 324          */
 325         public function offsetExists( $name ) {
 326                 return isset( $this->options[$name] );
 327         }
 328         /**
 329          * Retrieve an option value
 330          * @return Mixed
 331          */
 332         public function offsetGet( $name ) {
 333                 return $this->getValue( $name );
 334         }
 335         /**     Set an option to given value */
 336         public function offsetSet( $name, $value ) {
 337                 $this->setValue( $name, $value );
 338         }
 339         /**     Delete the option */
 340         public function offsetUnset( $name ) {
 341                 $this->delete( $name );
 342         }
 343         /* @} */
 344 }