includes/libs/ParamValidator/TypeDef.php

   1 <?php
   2
   3 namespace Wikimedia\ParamValidator;
   4
   5 use Wikimedia\Message\DataMessageValue;
   6 use Wikimedia\Message\MessageValue;
   7
   8 /**
   9  * Base definition for ParamValidator types.
  10  *
  11  * Most methods in this class accept an "options array". This is just the `$options`
  12  * passed to ParamValidator::getValue(), ParamValidator::validateValue(), and the like
  13  * and is intended for communication of non-global state to the Callbacks.
  14  *
  15  * @since 1.34
  16  * @unstable for use in extensions. Intended to become stable to extend, at
  17  *           least for use in MediaWiki, which already defines some subclasses.
  18  */
  19 abstract class TypeDef {
  20
  21         /**
  22          * @unstable Temporarily log warnings to detect misbehaving clients (T305973)
  23          */
  24         public const OPT_LOG_BAD_TYPES = 'log-bad-types';
  25
  26         /**
  27          * Option that instructs TypeDefs to enforce the native type of parameter
  28          * values, instead of allowing string values as input. This is intended for
  29          * use with values coming from a JSON request body, and may accommodate for
  30          * differences between the type system of PHP and JSON.
  31          */
  32         public const OPT_ENFORCE_JSON_TYPES = 'enforce-json-types';
  33
  34         /** @var Callbacks */
  35         protected $callbacks;
  36
  37         /**
  38          * @stable to call
  39          *
  40          * @param Callbacks $callbacks
  41          */
  42         public function __construct( Callbacks $callbacks ) {
  43                 $this->callbacks = $callbacks;
  44         }
  45
  46         /**
  47          * Whether the value may be an array.
  48          * Note that this is different from multi-value.
  49          * This should only return true if each value can be an array.
  50          * @since 1.41
  51          * @stable to override
  52          * @return bool
  53          */
  54         public function supportsArrays() {
  55                 return false;
  56         }
  57
  58         /**
  59          * Fails if $value is not a string.
  60          *
  61          * @param string $name Parameter name being validated.
  62          * @param mixed $value Value being validated.
  63          * @param array $settings Parameter settings array.
  64          * @param array $options Options array.
  65          *
  66          * @return void
  67          */
  68         protected function failIfNotString(
  69                 string $name,
  70                 $value,
  71                 array $settings,
  72                 array $options
  73         ): void {
  74                 if ( !is_string( $value ) ) {
  75                         $this->fatal(
  76                                 $this->failureMessage( 'needstring' )
  77                                         ->params( gettype( $value ) ),
  78                                 $name, $value, $settings, $options
  79                         );
  80                 }
  81         }
  82
  83         /**
  84          * Throw a ValidationException.
  85          * This is a wrapper for failure() which explicitly declares that it
  86          * never returns, which is useful to static analysis tools like Phan.
  87          *
  88          * Note that parameters for `$name` and `$value` are always added as `$1`
  89          * and `$2`.
  90          *
  91          * @param DataMessageValue|string $failure Failure code or message.
  92          * @param string $name Parameter name being validated.
  93          * @param mixed $value Value being validated.
  94          * @param array $settings Parameter settings array.
  95          * @param array $options Options array.
  96          * @return never
  97          * @throws ValidationException always
  98          */
  99         protected function fatal(
 100                 $failure, $name, $value, array $settings, array $options
 101         ) {
 102                 $this->failure( $failure, $name, $value, $settings, $options );
 103         }
 104
 105         /**
 106          * Record a failure message
 107          *
 108          * Depending on `$fatal`, this will either throw a ValidationException or
 109          * call $this->callbacks->recordCondition().
 110          *
 111          * Note that parameters for `$name` and `$value` are always added as `$1`
 112          * and `$2`.
 113          *
 114          * @param DataMessageValue|string $failure Failure code or message.
 115          * @param string $name Parameter name being validated.
 116          * @param mixed $value Value being validated.
 117          * @param array $settings Parameter settings array.
 118          * @param array $options Options array.
 119          * @param bool $fatal Whether the failure is fatal
 120          */
 121         protected function failure(
 122                 $failure, $name, $value, array $settings, array $options, $fatal = true
 123         ) {
 124                 if ( !is_string( $value ) ) {
 125                         $value = (string)$this->stringifyValue( $name, $value, $settings, $options );
 126                 }
 127
 128                 if ( is_string( $failure ) ) {
 129                         $mv = $this->failureMessage( $failure )
 130                                 ->plaintextParams( $name, $value );
 131                 } else {
 132                         $mv = DataMessageValue::new( $failure->getKey(), [], $failure->getCode(), $failure->getData() )
 133                                 ->plaintextParams( $name, $value )
 134                                 ->params( ...$failure->getParams() );
 135                 }
 136
 137                 if ( $fatal ) {
 138                         throw new ValidationException( $mv, $name, $value, $settings );
 139                 }
 140                 $this->callbacks->recordCondition( $mv, $name, $value, $settings, $options );
 141         }
 142
 143         /**
 144          * Create a DataMessageValue representing a failure
 145          *
 146          * The message key will be "paramvalidator-$code" or "paramvalidator-$code-$suffix".
 147          *
 148          * Use DataMessageValue's param mutators to add additional MessageParams.
 149          * Note that `failure()` will prepend parameters for `$name` and `$value`.
 150          *
 151          * @param string $code Failure code.
 152          * @param array|null $data Failure data.
 153          * @param string|null $suffix Suffix to append when producing the message key
 154          * @return DataMessageValue
 155          */
 156         protected function failureMessage( $code, ?array $data = null, $suffix = null ): DataMessageValue {
 157                 return DataMessageValue::new(
 158                         "paramvalidator-$code" . ( $suffix !== null ? "-$suffix" : '' ),
 159                         [], $code, $data
 160                 );
 161         }
 162
 163         /**
 164          * Get the value from the request
 165          * @stable to override
 166          *
 167          * @note Only override this if you need to use something other than
 168          *  $this->callbacks->getValue() to fetch the value. Reformatting from a
 169          *  string should typically be done by self::validate().
 170          * @note Handling of ParamValidator::PARAM_DEFAULT should be left to ParamValidator,
 171          *  as should PARAM_REQUIRED and the like.
 172          *
 173          * @param string $name Parameter name being fetched.
 174          * @param array $settings Parameter settings array.
 175          * @param array $options Options array.
 176          * @return null|mixed Return null if the value wasn't present, otherwise a
 177          *  value to be passed to self::validate().
 178          */
 179         public function getValue( $name, array $settings, array $options ) {
 180                 return $this->callbacks->getValue( $name, null, $options );
 181         }
 182
 183         /**
 184          * Validate the value
 185          *
 186          * When ParamValidator is processing a multi-valued parameter, this will be
 187          * called once for each of the supplied values. Which may mean zero calls.
 188          *
 189          * When getValue() returned null, this will not be called.
 190          *
 191          * @param string $name Parameter name being validated.
 192          * @param mixed $value Value to validate, from getValue().
 193          * @param array $settings Parameter settings array.
 194          * @param array $options Options array. Note the following values that may be set
 195          *  by ParamValidator:
 196          *   - is-default: (bool) If present and true, the value was taken from PARAM_DEFAULT rather
 197          *     that being supplied by the client.
 198          *   - values-list: (string[]) If defined, values of a multi-valued parameter are being processed
 199          *     (and this array holds the full set of values).
 200          * @return mixed Validated value
 201          * @throws ValidationException if the value is invalid
 202          */
 203         abstract public function validate( $name, $value, array $settings, array $options );
 204
 205         /**
 206          * Normalize a settings array
 207          * @stable to override
 208          * @param array $settings
 209          * @return array
 210          */
 211         public function normalizeSettings( array $settings ) {
 212                 return $settings;
 213         }
 214
 215         /**
 216          * Validate a parameter settings array
 217          *
 218          * This is intended for validation of parameter settings during unit or
 219          * integration testing, and should implement strict checks.
 220          *
 221          * The rest of the code should generally be more permissive.
 222          *
 223          * @see ParamValidator::checkSettings()
 224          * @stable to override
 225          *
 226          * @param string $name Parameter name
 227          * @param array|mixed $settings Default value or an array of settings
 228          *  using PARAM_* constants.
 229          * @param array $options Options array, passed through to the TypeDef and Callbacks.
 230          * @param array $ret
 231          *  - 'issues': (string[]) Errors detected in $settings, as English text. If the settings
 232          *    are valid, this will be the empty array. Keys on input are ParamValidator constants,
 233          *    allowing the typedef to easily override core validation; this need not be preserved
 234          *    when returned.
 235          *  - 'allowedKeys': (string[]) ParamValidator keys that are allowed in `$settings`.
 236          *  - 'messages': (MessageValue[]) Messages to be checked for existence.
 237          * @return array $ret, with any relevant changes.
 238          */
 239         public function checkSettings( string $name, $settings, array $options, array $ret ): array {
 240                 return $ret;
 241         }
 242
 243         /**
 244          * Get the values for enum-like parameters
 245          *
 246          * This is primarily intended for documentation and implementation of
 247          * PARAM_ALL; it is the responsibility of the TypeDef to ensure that validate()
 248          * accepts the values returned here.
 249          * @stable to override
 250          *
 251          * @param string $name Parameter name being validated.
 252          * @param array $settings Parameter settings array.
 253          * @param array $options Options array.
 254          * @return array|null All possible enumerated values, or null if this is
 255          *  not an enumeration.
 256          */
 257         public function getEnumValues( $name, array $settings, array $options ) {
 258                 return null;
 259         }
 260
 261         /**
 262          * Convert a value to a string representation.
 263          *
 264          * This is intended as the inverse of getValue() and validate(): this
 265          * should accept anything returned by those methods or expected to be used
 266          * as PARAM_DEFAULT, and if the string from this method is passed in as client
 267          * input or PARAM_DEFAULT it should give equivalent output from validate().
 268          *
 269          * @param string $name Parameter name being converted.
 270          * @param mixed $value Parameter value being converted. Do not pass null.
 271          * @param array $settings Parameter settings array.
 272          * @param array $options Options array.
 273          * @return string|null Return null if there is no representation of $value
 274          *  reasonably satisfying the description given.
 275          */
 276         public function stringifyValue( $name, $value, array $settings, array $options ) {
 277                 if ( is_array( $value ) ) {
 278                         return '(array)';
 279                 }
 280
 281                 return (string)$value;
 282         }
 283
 284         /**
 285          * Describe parameter settings in a machine-readable format.
 286          *
 287          * Keys should be short strings using lowercase ASCII letters. Values
 288          * should generally be values that could be encoded in JSON or the like.
 289          *
 290          * This is intended to handle PARAM constants specific to this class. It
 291          * generally shouldn't handle constants defined on ParamValidator itself.
 292          * @stable to override
 293          *
 294          * @param string $name Parameter name.
 295          * @param array $settings Parameter settings array.
 296          * @param array $options Options array.
 297          * @return array
 298          */
 299         public function getParamInfo( $name, array $settings, array $options ) {
 300                 return [];
 301         }
 302
 303         /**
 304          * Describe parameter settings in human-readable format
 305          *
 306          * Keys in the returned array should generally correspond to PARAM
 307          * constants.
 308          *
 309          * If relevant, a MessageValue describing the type itself should be
 310          * returned with key ParamValidator::PARAM_TYPE.
 311          *
 312          * The default messages for other ParamValidator-defined PARAM constants
 313          * may be suppressed by returning null as the value for those constants, or
 314          * replaced by returning a replacement MessageValue. Normally, however,
 315          * the default messages should not be changed.
 316          *
 317          * MessageValues describing any other constraints applied via PARAM
 318          * constants specific to this class should also be returned.
 319          * @stable to override
 320          *
 321          * @param string $name Parameter name being described.
 322          * @param array $settings Parameter settings array.
 323          * @param array $options Options array.
 324          * @return (MessageValue|null)[]
 325          */
 326         public function getHelpInfo( $name, array $settings, array $options ) {
 327                 return [];
 328         }
 329
 330 }