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  * Copyright © 2013, Bartosz Dziewoński
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  * @author Niklas Laxström
  26  * @author Antoine Musso
  27  */
  28
  29 /**
  30  * Helper class to keep track of options when mixing links and form elements.
  31  *
  32  * @todo This badly needs some examples and tests :) The usage in SpecialRecentchanges class is a
  33  *     good ersatz in the meantime.
  34  */
  35 class FormOptions implements ArrayAccess {
  36         /** @name Type constants
  37          * Used internally to map an option value to a WebRequest accessor
  38          */
  39         /* @{ */
  40         /** Mark value for automatic detection (for simple data types only) */
  41         const AUTO = -1;
  42         /** String type, maps guessType() to WebRequest::getText() */
  43         const STRING = 0;
  44         /** Integer type, maps guessType() to WebRequest::getInt() */
  45         const INT = 1;
  46         /** Float type, maps guessType() to WebRequest::getFloat()
  47          * @since 1.23 */
  48         const FLOAT = 4;
  49         /** Boolean type, maps guessType() to WebRequest::getBool() */
  50         const BOOL = 2;
  51         /** Integer type or null, maps to WebRequest::getIntOrNull()
  52          * This is useful for the namespace selector.
  53          */
  54         const INTNULL = 3;
  55         /* @} */
  56
  57         /**
  58          * Map of known option names to information about them.
  59          *
  60          * Each value is an array with the following keys:
  61          * - 'default' - the default value as passed to add()
  62          * - 'value' - current value, start with null, can be set by various functions
  63          * - 'consumed' - true/false, whether the option was consumed using
  64          *   consumeValue() or consumeValues()
  65          * - 'type' - one of the type constants (but never AUTO)
  66          */
  67         protected $options = array();
  68
  69         # Setting up
  70
  71         /**
  72          * Add an option to be handled by this FormOptions instance.
  73          *
  74          * @param string $name Request parameter name
  75          * @param mixed $default Default value when the request parameter is not present
  76          * @param int $type One of the type constants (optional, defaults to AUTO)
  77          */
  78         public function add( $name, $default, $type = self::AUTO ) {
  79                 $option = array();
  80                 $option['default'] = $default;
  81                 $option['value'] = null;
  82                 $option['consumed'] = false;
  83
  84                 if ( $type !== self::AUTO ) {
  85                         $option['type'] = $type;
  86                 } else {
  87                         $option['type'] = self::guessType( $default );
  88                 }
  89
  90                 $this->options[$name] = $option;
  91         }
  92
  93         /**
  94          * Remove an option being handled by this FormOptions instance. This is the inverse of add().
  95          *
  96          * @param string $name Request parameter name
  97          */
  98         public function delete( $name ) {
  99                 $this->validateName( $name, true );
 100                 unset( $this->options[$name] );
 101         }
 102
 103         /**
 104          * Used to find out which type the data is. All types are defined in the 'Type constants' section
 105          * of this class.
 106          *
 107          * Detection of the INTNULL type is not supported; INT will be assumed if the data is an integer,
 108          * MWException will be thrown if it's null.
 109          *
 110          * @param mixed $data Value to guess the type for
 111          * @throws MWException If unable to guess the type
 112          * @return int Type constant
 113          */
 114         public static function guessType( $data ) {
 115                 if ( is_bool( $data ) ) {
 116                         return self::BOOL;
 117                 } elseif ( is_int( $data ) ) {
 118                         return self::INT;
 119                 } elseif ( is_float( $data ) ) {
 120                         return self::FLOAT;
 121                 } elseif ( is_string( $data ) ) {
 122                         return self::STRING;
 123                 } else {
 124                         throw new MWException( 'Unsupported datatype' );
 125                 }
 126         }
 127
 128         # Handling values
 129
 130         /**
 131          * Verify that the given option name exists.
 132          *
 133          * @param string $name Option name
 134          * @param bool $strict Throw an exception when the option doesn't exist instead of returning false
 135          * @throws MWException
 136          * @return bool True if the option exists, false otherwise
 137          */
 138         public function validateName( $name, $strict = false ) {
 139                 if ( !isset( $this->options[$name] ) ) {
 140                         if ( $strict ) {
 141                                 throw new MWException( "Invalid option $name" );
 142                         } else {
 143                                 return false;
 144                         }
 145                 }
 146
 147                 return true;
 148         }
 149
 150         /**
 151          * Use to set the value of an option.
 152          *
 153          * @param string $name Option name
 154          * @param mixed $value Value for the option
 155          * @param bool $force Whether to set the value when it is equivalent to the default value for this
 156          *     option (default false).
 157          */
 158         public function setValue( $name, $value, $force = false ) {
 159                 $this->validateName( $name, true );
 160
 161                 if ( !$force && $value === $this->options[$name]['default'] ) {
 162                         // null default values as unchanged
 163                         $this->options[$name]['value'] = null;
 164                 } else {
 165                         $this->options[$name]['value'] = $value;
 166                 }
 167         }
 168
 169         /**
 170          * Get the value for the given option name. Uses getValueReal() internally.
 171          *
 172          * @param string $name Option name
 173          * @return mixed
 174          */
 175         public function getValue( $name ) {
 176                 $this->validateName( $name, true );
 177
 178                 return $this->getValueReal( $this->options[$name] );
 179         }
 180
 181         /**
 182          * Return current option value, based on a structure taken from $options.
 183          *
 184          * @param array $option Array structure describing the option
 185          * @return mixed Value, or the default value if it is null
 186          */
 187         protected function getValueReal( $option ) {
 188                 if ( $option['value'] !== null ) {
 189                         return $option['value'];
 190                 } else {
 191                         return $option['default'];
 192                 }
 193         }
 194
 195         /**
 196          * Delete the option value.
 197          * This will make future calls to getValue() return the default value.
 198          * @param string $name Option name
 199          */
 200         public function reset( $name ) {
 201                 $this->validateName( $name, true );
 202                 $this->options[$name]['value'] = null;
 203         }
 204
 205         /**
 206          * Get the value of given option and mark it as 'consumed'. Consumed options are not returned
 207          * by getUnconsumedValues().
 208          *
 209          * @see consumeValues()
 210          * @throws MWException If the option does not exist
 211          * @param string $name Option name
 212          * @return mixed Value, or the default value if it is null
 213          */
 214         public function consumeValue( $name ) {
 215                 $this->validateName( $name, true );
 216                 $this->options[$name]['consumed'] = true;
 217
 218                 return $this->getValueReal( $this->options[$name] );
 219         }
 220
 221         /**
 222          * Get the values of given options and mark them as 'consumed'. Consumed options are not returned
 223          * by getUnconsumedValues().
 224          *
 225          * @see consumeValue()
 226          * @throws MWException If any option does not exist
 227          * @param array $names Array of option names as strings
 228          * @return array Array of option values, or the default values if they are null
 229          */
 230         public function consumeValues( $names ) {
 231                 $out = array();
 232
 233                 foreach ( $names as $name ) {
 234                         $this->validateName( $name, true );
 235                         $this->options[$name]['consumed'] = true;
 236                         $out[] = $this->getValueReal( $this->options[$name] );
 237                 }
 238
 239                 return $out;
 240         }
 241
 242         /**
 243          * @see validateBounds()
 244          */
 245         public function validateIntBounds( $name, $min, $max ) {
 246                 $this->validateBounds( $name, $min, $max );
 247         }
 248
 249         /**
 250          * Constrain a numeric value for a given option to a given range. The value will be altered to fit
 251          * in the range.
 252          *
 253          * @since 1.23
 254          *
 255          * @param string $name Option name
 256          * @param int|float $min Minimum value
 257          * @param int|float $max Maximum value
 258          * @throws MWException If option is not of type INT
 259          */
 260         public function validateBounds( $name, $min, $max ) {
 261                 $this->validateName( $name, true );
 262                 $type = $this->options[$name]['type'];
 263
 264                 if ( $type !== self::INT && $type !== self::FLOAT ) {
 265                         throw new MWException( "Option $name is not of type INT or FLOAT" );
 266                 }
 267
 268                 $value = $this->getValueReal( $this->options[$name] );
 269                 $value = max( $min, min( $max, $value ) );
 270
 271                 $this->setValue( $name, $value );
 272         }
 273
 274         /**
 275          * Get all remaining values which have not been consumed by consumeValue() or consumeValues().
 276          *
 277          * @param bool $all Whether to include unchanged options (default: false)
 278          * @return array
 279          */
 280         public function getUnconsumedValues( $all = false ) {
 281                 $values = array();
 282
 283                 foreach ( $this->options as $name => $data ) {
 284                         if ( !$data['consumed'] ) {
 285                                 if ( $all || $data['value'] !== null ) {
 286                                         $values[$name] = $this->getValueReal( $data );
 287                                 }
 288                         }
 289                 }
 290
 291                 return $values;
 292         }
 293
 294         /**
 295          * Return options modified as an array ( name => value )
 296          * @return array
 297          */
 298         public function getChangedValues() {
 299                 $values = array();
 300
 301                 foreach ( $this->options as $name => $data ) {
 302                         if ( $data['value'] !== null ) {
 303                                 $values[$name] = $data['value'];
 304                         }
 305                 }
 306
 307                 return $values;
 308         }
 309
 310         /**
 311          * Format options to an array ( name => value )
 312          * @return array
 313          */
 314         public function getAllValues() {
 315                 $values = array();
 316
 317                 foreach ( $this->options as $name => $data ) {
 318                         $values[$name] = $this->getValueReal( $data );
 319                 }
 320
 321                 return $values;
 322         }
 323
 324         # Reading values
 325
 326         /**
 327          * Fetch values for all options (or selected options) from the given WebRequest, making them
 328          * available for accessing with getValue() or consumeValue() etc.
 329          *
 330          * @param WebRequest $r The request to fetch values from
 331          * @param array $optionKeys Which options to fetch the values for (default:
 332          *     all of them). Note that passing an empty array will also result in
 333          *     values for all keys being fetched.
 334          * @throws MWException If the type of any option is invalid
 335          */
 336         public function fetchValuesFromRequest( WebRequest $r, $optionKeys = null ) {
 337                 if ( !$optionKeys ) {
 338                         $optionKeys = array_keys( $this->options );
 339                 }
 340
 341                 foreach ( $optionKeys as $name ) {
 342                         $default = $this->options[$name]['default'];
 343                         $type = $this->options[$name]['type'];
 344
 345                         switch ( $type ) {
 346                                 case self::BOOL:
 347                                         $value = $r->getBool( $name, $default );
 348                                         break;
 349                                 case self::INT:
 350                                         $value = $r->getInt( $name, $default );
 351                                         break;
 352                                 case self::FLOAT:
 353                                         $value = $r->getFloat( $name, $default );
 354                                         break;
 355                                 case self::STRING:
 356                                         $value = $r->getText( $name, $default );
 357                                         break;
 358                                 case self::INTNULL:
 359                                         $value = $r->getIntOrNull( $name );
 360                                         break;
 361                                 default:
 362                                         throw new MWException( 'Unsupported datatype' );
 363                         }
 364
 365                         if ( $value !== null ) {
 366                                 $this->options[$name]['value'] = $value === $default ? null : $value;
 367                         }
 368                 }
 369         }
 370
 371         /** @name ArrayAccess functions
 372          * These functions implement the ArrayAccess PHP interface.
 373          * @see http://php.net/manual/en/class.arrayaccess.php
 374          */
 375         /* @{ */
 376         /**
 377          * Whether the option exists.
 378          * @param string $name
 379          * @return bool
 380          */
 381         public function offsetExists( $name ) {
 382                 return isset( $this->options[$name] );
 383         }
 384
 385         /**
 386          * Retrieve an option value.
 387          * @param string $name
 388          * @return mixed
 389          */
 390         public function offsetGet( $name ) {
 391                 return $this->getValue( $name );
 392         }
 393
 394         /**
 395          * Set an option to given value.
 396          * @param string $name
 397          * @param mixed $value
 398          */
 399         public function offsetSet( $name, $value ) {
 400                 $this->setValue( $name, $value );
 401         }
 402
 403         /**
 404          * Delete the option.
 405          * @param string $name
 406          */
 407         public function offsetUnset( $name ) {
 408                 $this->delete( $name );
 409         }
 410         /* @} */
 411 }