includes/libs/ParamValidator/TypeDef/EnumDef.php

   1 <?php
   2
   3 namespace Wikimedia\ParamValidator\TypeDef;
   4
   5 use Wikimedia\ParamValidator\ParamValidator;
   6 use Wikimedia\ParamValidator\TypeDef;
   7 use Wikimedia\ParamValidator\ValidationException;
   8
   9 /**
  10  * Type definition for enumeration types.
  11  *
  12  * This class expects that PARAM_TYPE is an array of allowed values. Subclasses
  13  * may override getEnumValues() to determine the allowed values differently.
  14  *
  15  * The result from validate() is one of the defined values.
  16  *
  17  * ValidationException codes:
  18  *  - 'badvalue': The value is not a recognized value. No data.
  19  *  - 'notmulti': PARAM_ISMULTI is not set and the unrecognized value seems to
  20  *     be an attempt at using multiple values. No data.
  21  *
  22  * Additional codes may be generated when using certain PARAM constants. See
  23  * the constants' documentation for details.
  24  *
  25  * @since 1.34
  26  * @unstable
  27  */
  28 class EnumDef extends TypeDef {
  29
  30         /**
  31          * (array) Associative array of deprecated values.
  32          *
  33          * Keys are the deprecated parameter values, values are included in
  34          * the ValidationException. If value is null, the parameter is considered
  35          * not actually deprecated.
  36          *
  37          * Note that this does not add any values to the enumeration, it only
  38          * documents existing values as being deprecated.
  39          *
  40          * ValidationException codes: (non-fatal)
  41          *  - 'deprecated-value': A deprecated value was encountered. Data:
  42          *     - 'flag': The value from the associative array.
  43          */
  44         const PARAM_DEPRECATED_VALUES = 'param-deprecated-values';
  45
  46         public function validate( $name, $value, array $settings, array $options ) {
  47                 $values = $this->getEnumValues( $name, $settings, $options );
  48
  49                 if ( in_array( $value, $values, true ) ) {
  50                         // Set a warning if a deprecated parameter value has been passed
  51                         if ( isset( $settings[self::PARAM_DEPRECATED_VALUES][$value] ) ) {
  52                                 $this->callbacks->recordCondition(
  53                                         new ValidationException( $name, $value, $settings, 'deprecated-value', [
  54                                                 'flag' => $settings[self::PARAM_DEPRECATED_VALUES][$value],
  55                                         ] ),
  56                                         $options
  57                                 );
  58                         }
  59
  60                         return $value;
  61                 }
  62
  63                 if ( !isset( $options['values-list'] ) &&
  64                         count( ParamValidator::explodeMultiValue( $value, 2 ) ) > 1
  65                 ) {
  66                         throw new ValidationException( $name, $value, $settings, 'notmulti', [] );
  67                 } else {
  68                         throw new ValidationException( $name, $value, $settings, 'badvalue', [] );
  69                 }
  70         }
  71
  72         public function getEnumValues( $name, array $settings, array $options ) {
  73                 return $settings[ParamValidator::PARAM_TYPE];
  74         }
  75
  76         public function stringifyValue( $name, $value, array $settings, array $options ) {
  77                 if ( !is_array( $value ) ) {
  78                         return parent::stringifyValue( $name, $value, $settings, $options );
  79                 }
  80
  81                 foreach ( $value as $v ) {
  82                         if ( strpos( $v, '|' ) !== false ) {
  83                                 return "\x1f" . implode( "\x1f", $value );
  84                         }
  85                 }
  86                 return implode( '|', $value );
  87         }
  88
  89 }