MediaWiki  master
FormOptions.php
Go to the documentation of this file.
1 <?php
35 class FormOptions implements ArrayAccess {
39  /* @{ */
41  const AUTO = -1;
43  const STRING = 0;
45  const INT = 1;
49  const FLOAT = 4;
51  const BOOL = 2;
55  const INTNULL = 3;
59  const ARR = 5;
60  /* @} */
61 
72  protected $options = [];
73 
74  # Setting up
75 
83  public function add( $name, $default, $type = self::AUTO ) {
84  $option = [];
85  $option['default'] = $default;
86  $option['value'] = null;
87  $option['consumed'] = false;
88 
89  if ( $type !== self::AUTO ) {
90  $option['type'] = $type;
91  } else {
92  $option['type'] = self::guessType( $default );
93  }
94 
95  $this->options[$name] = $option;
96  }
97 
103  public function delete( $name ) {
104  $this->validateName( $name, true );
105  unset( $this->options[$name] );
106  }
107 
119  public static function guessType( $data ) {
120  if ( is_bool( $data ) ) {
121  return self::BOOL;
122  } elseif ( is_int( $data ) ) {
123  return self::INT;
124  } elseif ( is_float( $data ) ) {
125  return self::FLOAT;
126  } elseif ( is_string( $data ) ) {
127  return self::STRING;
128  } elseif ( is_array( $data ) ) {
129  return self::ARR;
130  } else {
131  throw new MWException( 'Unsupported datatype' );
132  }
133  }
134 
135  # Handling values
136 
145  public function validateName( $name, $strict = false ) {
146  if ( !isset( $this->options[$name] ) ) {
147  if ( $strict ) {
148  throw new MWException( "Invalid option $name" );
149  } else {
150  return false;
151  }
152  }
153 
154  return true;
155  }
156 
165  public function setValue( $name, $value, $force = false ) {
166  $this->validateName( $name, true );
167 
168  if ( !$force && $value === $this->options[$name]['default'] ) {
169  // null default values as unchanged
170  $this->options[$name]['value'] = null;
171  } else {
172  $this->options[$name]['value'] = $value;
173  }
174  }
175 
182  public function getValue( $name ) {
183  $this->validateName( $name, true );
184 
185  return $this->getValueReal( $this->options[$name] );
186  }
187 
194  protected function getValueReal( $option ) {
195  if ( $option['value'] !== null ) {
196  return $option['value'];
197  } else {
198  return $option['default'];
199  }
200  }
201 
207  public function reset( $name ) {
208  $this->validateName( $name, true );
209  $this->options[$name]['value'] = null;
210  }
211 
221  public function consumeValue( $name ) {
222  $this->validateName( $name, true );
223  $this->options[$name]['consumed'] = true;
224 
225  return $this->getValueReal( $this->options[$name] );
226  }
227 
237  public function consumeValues( $names ) {
238  $out = [];
239 
240  foreach ( $names as $name ) {
241  $this->validateName( $name, true );
242  $this->options[$name]['consumed'] = true;
243  $out[] = $this->getValueReal( $this->options[$name] );
244  }
245 
246  return $out;
247  }
248 
255  public function validateIntBounds( $name, $min, $max ) {
256  $this->validateBounds( $name, $min, $max );
257  }
258 
270  public function validateBounds( $name, $min, $max ) {
271  $this->validateName( $name, true );
272  $type = $this->options[$name]['type'];
273 
274  if ( $type !== self::INT && $type !== self::FLOAT ) {
275  throw new MWException( "Option $name is not of type INT or FLOAT" );
276  }
277 
278  $value = $this->getValueReal( $this->options[$name] );
279  $value = max( $min, min( $max, $value ) );
280 
281  $this->setValue( $name, $value );
282  }
283 
290  public function getUnconsumedValues( $all = false ) {
291  $values = [];
292 
293  foreach ( $this->options as $name => $data ) {
294  if ( !$data['consumed'] ) {
295  if ( $all || $data['value'] !== null ) {
296  $values[$name] = $this->getValueReal( $data );
297  }
298  }
299  }
300 
301  return $values;
302  }
303 
308  public function getChangedValues() {
309  $values = [];
310 
311  foreach ( $this->options as $name => $data ) {
312  if ( $data['value'] !== null ) {
313  $values[$name] = $data['value'];
314  }
315  }
316 
317  return $values;
318  }
319 
324  public function getAllValues() {
325  $values = [];
326 
327  foreach ( $this->options as $name => $data ) {
328  $values[$name] = $this->getValueReal( $data );
329  }
330 
331  return $values;
332  }
333 
334  # Reading values
335 
346  public function fetchValuesFromRequest( WebRequest $r, $optionKeys = null ) {
347  if ( !$optionKeys ) {
348  $optionKeys = array_keys( $this->options );
349  }
350 
351  foreach ( $optionKeys as $name ) {
352  $default = $this->options[$name]['default'];
353  $type = $this->options[$name]['type'];
354 
355  switch ( $type ) {
356  case self::BOOL:
357  $value = $r->getBool( $name, $default );
358  break;
359  case self::INT:
360  $value = $r->getInt( $name, $default );
361  break;
362  case self::FLOAT:
363  $value = $r->getFloat( $name, $default );
364  break;
365  case self::STRING:
366  $value = $r->getText( $name, $default );
367  break;
368  case self::INTNULL:
369  $value = $r->getIntOrNull( $name );
370  break;
371  case self::ARR:
372  $value = $r->getArray( $name );
373  break;
374  default:
375  throw new MWException( 'Unsupported datatype' );
376  }
377 
378  if ( $value !== null ) {
379  $this->options[$name]['value'] = $value === $default ? null : $value;
380  }
381  }
382  }
383 
388  /* @{ */
389 
395  public function offsetExists( $name ) {
396  return isset( $this->options[$name] );
397  }
398 
404  public function offsetGet( $name ) {
405  return $this->getValue( $name );
406  }
407 
413  public function offsetSet( $name, $value ) {
414  $this->setValue( $name, $value );
415  }
416 
421  public function offsetUnset( $name ) {
422  $this->delete( $name );
423  }
424  /* @} */
425 }
Helper class to keep track of options when mixing links and form elements.
Definition: FormOptions.php:35
const BOOL
Boolean type, maps guessType() to WebRequest::getBool()
Definition: FormOptions.php:51
const FLOAT
Float type, maps guessType() to WebRequest::getFloat()
Definition: FormOptions.php:49
getInt( $name, $default=0)
Fetch an integer value from the input or return $default if not set.
Definition: WebRequest.php:575
const INTNULL
Integer type or null, maps to WebRequest::getIntOrNull() This is useful for the namespace selector...
Definition: FormOptions.php:55
consumeValues( $names)
Get the values of given options and mark them as &#39;consumed&#39;.
reset( $name)
Delete the option value.
offsetUnset( $name)
Delete the option.
consumeValue( $name)
Get the value of given option and mark it as &#39;consumed&#39;.
getUnconsumedValues( $all=false)
Get all remaining values which have not been consumed by consumeValue() or consumeValues().
getFloat( $name, $default=0.0)
Fetch a floating point value from the input or return $default if not set.
Definition: WebRequest.php:604
add( $name, $default, $type=self::AUTO)
Add an option to be handled by this FormOptions instance.
Definition: FormOptions.php:83
validateIntBounds( $name, $min, $max)
getBool( $name, $default=false)
Fetch a boolean value from the input or return $default if not set.
Definition: WebRequest.php:617
fetchValuesFromRequest(WebRequest $r, $optionKeys=null)
Fetch values for all options (or selected options) from the given WebRequest, making them available f...
const ARR
Array type, maps guessType() to WebRequest::getArray()
Definition: FormOptions.php:59
validateBounds( $name, $min, $max)
Constrain a numeric value for a given option to a given range.
offsetSet( $name, $value)
Set an option to given value.
getValueReal( $option)
Return current option value, based on a structure taken from $options.
const INT
Integer type, maps guessType() to WebRequest::getInt()
Definition: FormOptions.php:45
$options
Map of known option names to information about them.
Definition: FormOptions.php:72
static guessType( $data)
Used to find out which type the data is.
getText( $name, $default='')
Fetch a text string from the given array or return $default if it&#39;s not set.
Definition: WebRequest.php:659
setValue( $name, $value, $force=false)
Use to set the value of an option.
const STRING
String type, maps guessType() to WebRequest::getText()
Definition: FormOptions.php:43
offsetExists( $name)
Whether the option exists.
getArray( $name, $default=null)
Fetch an array from the input or return $default if it&#39;s not set.
Definition: WebRequest.php:539
getIntOrNull( $name)
Fetch an integer value from the input or return null if empty.
Definition: WebRequest.php:587
getChangedValues()
Return options modified as an array ( name => value )
getAllValues()
Format options to an array ( name => value )
validateName( $name, $strict=false)
Verify that the given option name exists.
getValue( $name)
Get the value for the given option name.
const AUTO
Mark value for automatic detection (for simple data types only)
Definition: FormOptions.php:41
offsetGet( $name)
Retrieve an option value.