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