includes/libs/ParamValidator/TypeDef.php

   1 <?php
   2
   3 namespace Wikimedia\ParamValidator;
   4
   5 /**
   6  * Base definition for ParamValidator types.
   7  *
   8  * All methods in this class accept an "options array". This is just the `$options`
   9  * passed to ParamValidator::getValue(), ParamValidator::validateValue(), and the like
  10  * and is intended for communication of non-global state.
  11  *
  12  * @since 1.34
  13  */
  14 abstract class TypeDef {
  15
  16         /** @var Callbacks */
  17         protected $callbacks;
  18
  19         public function __construct( Callbacks $callbacks ) {
  20                 $this->callbacks = $callbacks;
  21         }
  22
  23         /**
  24          * Get the value from the request
  25          *
  26          * @note Only override this if you need to use something other than
  27          *  $this->callbacks->getValue() to fetch the value. Reformatting from a
  28          *  string should typically be done by self::validate().
  29          * @note Handling of ParamValidator::PARAM_DEFAULT should be left to ParamValidator,
  30          *  as should PARAM_REQUIRED and the like.
  31          *
  32          * @param string $name Parameter name being fetched.
  33          * @param array $settings Parameter settings array.
  34          * @param array $options Options array.
  35          * @return null|mixed Return null if the value wasn't present, otherwise a
  36          *  value to be passed to self::validate().
  37          */
  38         public function getValue( $name, array $settings, array $options ) {
  39                 return $this->callbacks->getValue( $name, null, $options );
  40         }
  41
  42         /**
  43          * Validate the value
  44          *
  45          * When ParamValidator is processing a multi-valued parameter, this will be
  46          * called once for each of the supplied values. Which may mean zero calls.
  47          *
  48          * When getValue() returned null, this will not be called.
  49          *
  50          * @param string $name Parameter name being validated.
  51          * @param mixed $value Value to validate, from getValue().
  52          * @param array $settings Parameter settings array.
  53          * @param array $options Options array. Note the following values that may be set
  54          *  by ParamValidator:
  55          *   - values-list: (string[]) If defined, values of a multi-valued parameter are being processed
  56          *     (and this array holds the full set of values).
  57          * @return mixed Validated value
  58          * @throws ValidationException if the value is invalid
  59          */
  60         abstract public function validate( $name, $value, array $settings, array $options );
  61
  62         /**
  63          * Normalize a settings array
  64          * @param array $settings
  65          * @return array
  66          */
  67         public function normalizeSettings( array $settings ) {
  68                 return $settings;
  69         }
  70
  71         /**
  72          * Get the values for enum-like parameters
  73          *
  74          * This is primarily intended for documentation and implementation of
  75          * PARAM_ALL; it is the responsibility of the TypeDef to ensure that validate()
  76          * accepts the values returned here.
  77          *
  78          * @param string $name Parameter name being validated.
  79          * @param array $settings Parameter settings array.
  80          * @param array $options Options array.
  81          * @return array|null All possible enumerated values, or null if this is
  82          *  not an enumeration.
  83          */
  84         public function getEnumValues( $name, array $settings, array $options ) {
  85                 return null;
  86         }
  87
  88         /**
  89          * Convert a value to a string representation.
  90          *
  91          * This is intended as the inverse of getValue() and validate(): this
  92          * should accept anything returned by those methods or expected to be used
  93          * as PARAM_DEFAULT, and if the string from this method is passed in as client
  94          * input or PARAM_DEFAULT it should give equivalent output from validate().
  95          *
  96          * @param string $name Parameter name being converted.
  97          * @param mixed $value Parameter value being converted. Do not pass null.
  98          * @param array $settings Parameter settings array.
  99          * @param array $options Options array.
 100          * @return string|null Return null if there is no representation of $value
 101          *  reasonably satisfying the description given.
 102          */
 103         public function stringifyValue( $name, $value, array $settings, array $options ) {
 104                 return (string)$value;
 105         }
 106
 107         /**
 108          * "Describe" a settings array
 109          *
 110          * This is intended to format data about a settings array using this type
 111          * in a way that would be useful for automatically generated documentation
 112          * or a machine-readable interface specification.
 113          *
 114          * Keys in the description array should follow the same guidelines as the
 115          * code described for ValidationException.
 116          *
 117          * By default, each value in the description array is a single string,
 118          * integer, or array. When `$options['compact']` is supplied, each value is
 119          * instead an array of such and related values may be combined. For example,
 120          * a non-compact description for an integer type might include
 121          * `[ 'default' => 0, 'min' => 0, 'max' => 5 ]`, while in compact mode it might
 122          * instead report `[ 'default' => [ 'value' => 0 ], 'minmax' => [ 'min' => 0, 'max' => 5 ] ]`
 123          * to facilitate auto-generated documentation turning that 'minmax' into
 124          * "Value must be between 0 and 5" rather than disconnected statements
 125          * "Value must be >= 0" and "Value must be <= 5".
 126          *
 127          * @param string $name Parameter name being described.
 128          * @param array $settings Parameter settings array.
 129          * @param array $options Options array. Defined options for this base class are:
 130          *  - 'compact': (bool) Enable compact mode, as described above.
 131          * @return array
 132          */
 133         public function describeSettings( $name, array $settings, array $options ) {
 134                 $compact = !empty( $options['compact'] );
 135
 136                 $ret = [];
 137
 138                 if ( isset( $settings[ParamValidator::PARAM_DEFAULT] ) ) {
 139                         $value = $this->stringifyValue(
 140                                 $name, $settings[ParamValidator::PARAM_DEFAULT], $settings, $options
 141                         );
 142                         $ret['default'] = $compact ? [ 'value' => $value ] : $value;
 143                 }
 144
 145                 return $ret;
 146         }
 147
 148 }