MediaWiki  master
EnumDef.php
Go to the documentation of this file.
1 <?php
2 
4 
14 
32 class EnumDef extends TypeDef {
33 
49  public const PARAM_DEPRECATED_VALUES = 'param-deprecated-values';
50 
51  public function validate( $name, $value, array $settings, array $options ) {
52  $values = $this->getEnumValues( $name, $settings, $options );
53 
54  if ( in_array( $value, $values, true ) ) {
55  // Set a warning if a deprecated parameter value has been passed
56  if ( empty( $options['is-default'] ) &&
57  isset( $settings[self::PARAM_DEPRECATED_VALUES][$value] )
58  ) {
59  $msg = $settings[self::PARAM_DEPRECATED_VALUES][$value];
60  if ( $msg instanceof MessageValue ) {
61  $message = DataMessageValue::new(
62  $msg->getKey(),
63  $msg->getParams(),
64  'deprecated-value',
65  $msg instanceof DataMessageValue ? $msg->getData() : null
66  );
67  } else {
68  $message = $this->failureMessage( 'deprecated-value' );
69  }
70  $this->failure( $message, $name, $value, $settings, $options, false );
71  }
72 
73  return $value;
74  }
75 
76  $isMulti = isset( $options['values-list'] );
77  $this->failure(
78  $this->failureMessage( 'badvalue', [], $isMulti ? 'enummulti' : 'enumnotmulti' )
79  ->textListParams( array_map( static function ( $v ) {
80  return new ScalarParam( ParamType::PLAINTEXT, $v );
81  }, $values ) )
82  ->numParams( count( $values ) ),
83  $name, $value, $settings, $options
84  );
85  }
86 
87  public function checkSettings( string $name, $settings, array $options, array $ret ): array {
88  $ret = parent::checkSettings( $name, $settings, $options, $ret );
89 
90  $ret['allowedKeys'][] = self::PARAM_DEPRECATED_VALUES;
91 
92  $dv = $settings[self::PARAM_DEPRECATED_VALUES] ?? [];
93  if ( !is_array( $dv ) ) {
94  $ret['issues'][self::PARAM_DEPRECATED_VALUES] = 'PARAM_DEPRECATED_VALUES must be an array, got '
95  . gettype( $dv );
96  } else {
97  $values = array_map( function ( $v ) use ( $name, $settings, $options ) {
98  return $this->stringifyValue( $name, $v, $settings, $options );
99  }, $this->getEnumValues( $name, $settings, $options ) );
100  foreach ( $dv as $k => $v ) {
101  $k = $this->stringifyValue( $name, $k, $settings, $options );
102  if ( !in_array( $k, $values, true ) ) {
103  $ret['issues'][] = "PARAM_DEPRECATED_VALUES contains \"$k\", which is not "
104  . 'one of the enumerated values';
105  } elseif ( $v instanceof MessageValue ) {
106  $ret['messages'][] = $v;
107  } elseif ( $v !== null && $v !== true ) {
108  $type = $v === false ? 'false' : ( is_object( $v ) ? get_class( $v ) : gettype( $v ) );
109  $ret['issues'][] = 'Values in PARAM_DEPRECATED_VALUES must be null, true, or MessageValue, '
110  . "but value for \"$k\" is $type";
111  }
112  }
113  }
114 
115  return $ret;
116  }
117 
118  public function getEnumValues( $name, array $settings, array $options ) {
119  return array_values( $settings[ParamValidator::PARAM_TYPE] );
120  }
121 
122  public function stringifyValue( $name, $value, array $settings, array $options ) {
123  if ( !is_array( $value ) ) {
124  return parent::stringifyValue( $name, $value, $settings, $options );
125  }
126 
127  return ParamValidator::implodeMultiValue( $value );
128  }
129 
130  public function getParamInfo( $name, array $settings, array $options ) {
131  $info = parent::getParamInfo( $name, $settings, $options );
132 
133  $info['type'] = $this->sortEnumValues(
134  $name,
135  $this->getEnumValues( $name, $settings, $options ),
136  $settings,
137  $options
138  );
139 
140  if ( !empty( $settings[self::PARAM_DEPRECATED_VALUES] ) ) {
141  $deprecatedValues = array_intersect(
142  array_keys( $settings[self::PARAM_DEPRECATED_VALUES] ),
143  $this->getEnumValues( $name, $settings, $options )
144  );
145  if ( $deprecatedValues ) {
146  $deprecatedValues = $this->sortEnumValues( $name, $deprecatedValues, $settings, $options );
147  $info['deprecatedvalues'] = array_values( $deprecatedValues );
148  }
149  }
150 
151  return $info;
152  }
153 
154  public function getHelpInfo( $name, array $settings, array $options ) {
155  $info = parent::getHelpInfo( $name, $settings, $options );
156 
157  $isMulti = !empty( $settings[ParamValidator::PARAM_ISMULTI] );
158 
159  $values = $this->getEnumValuesForHelp( $name, $settings, $options );
160  $count = count( $values );
161 
162  $i = array_search( '', $values, true );
163  if ( $i === false ) {
164  $valuesParam = new ListParam( ListType::COMMA, $values );
165  } else {
166  unset( $values[$i] );
167  $valuesParam = MessageValue::new( 'paramvalidator-help-type-enum-can-be-empty' )
168  ->commaListParams( $values )
169  ->numParams( count( $values ) );
170  }
171 
172  $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-enum' )
173  ->params( $isMulti ? 2 : 1 )
174  ->params( $valuesParam )
175  ->numParams( $count );
176 
177  // Suppress standard ISMULTI message, it should be incorporated into our type message.
178  $info[ParamValidator::PARAM_ISMULTI] = null;
179 
180  return $info;
181  }
182 
192  protected function sortEnumValues(
193  string $name, array $values, array $settings, array $options
194  ): array {
195  // sort values by deprecation status and name
196  $flags = [];
197  foreach ( $values as $k => $value ) {
198  $flag = 0;
199  if ( isset( $settings[self::PARAM_DEPRECATED_VALUES][$value] ) ) {
200  $flag |= 1;
201  }
202  $flags[$k] = $flag;
203  }
204  array_multisort( $flags, $values, SORT_NATURAL );
205 
206  return $values;
207  }
208 
217  protected function getEnumValuesForHelp( $name, array $settings, array $options ) {
218  $values = $this->getEnumValues( $name, $settings, $options );
219  $values = $this->sortEnumValues( $name, $values, $settings, $options );
220 
221  // @todo Indicate deprecated values in some manner. Probably that needs
222  // MessageValue and/or MessageParam to have a generic ability to wrap
223  // values in HTML without that HTML coming out in the text format too.
224 
225  return $values;
226  }
227 
228 }
Value object representing a message for i18n with alternative machine-readable data.
getData()
Get the message's structured data.
static new( $key, $params=[], $code=null, array $data=null)
Static constructor for easier chaining of ->params() methods.
Value object representing a message parameter that consists of a list of values.
Definition: ListParam.php:12
The constants used to specify list types.
Definition: ListType.php:9
Value object representing a message parameter that consists of a list of values.
Value object representing a message for i18n.
static new( $key, $params=[])
Static constructor for easier chaining of ->params() methods.
The constants used to specify parameter types.
Definition: ParamType.php:11
const PLAINTEXT
A text parameter which is substituted after formatter processing.
Definition: ParamType.php:97
Value object representing a message parameter holding a single value.
Definition: ScalarParam.php:14
Service for formatting and validating API parameters.
const PARAM_ISMULTI
(bool) Indicate that the parameter is multi-valued.
static implodeMultiValue(array $value)
Implode an array as a multi-valued parameter string, like implode()
const PARAM_TYPE
(string|array) Type of the parameter.
Type definition for enumeration types.
Definition: EnumDef.php:32
validate( $name, $value, array $settings, array $options)
Validate the value.
Definition: EnumDef.php:51
getHelpInfo( $name, array $settings, array $options)
Describe parameter settings in human-readable format.
Definition: EnumDef.php:154
getEnumValues( $name, array $settings, array $options)
Get the values for enum-like parameters.
Definition: EnumDef.php:118
checkSettings(string $name, $settings, array $options, array $ret)
Validate a parameter settings array.
Definition: EnumDef.php:87
stringifyValue( $name, $value, array $settings, array $options)
Convert a value to a string representation.
Definition: EnumDef.php:122
getParamInfo( $name, array $settings, array $options)
Describe parameter settings in a machine-readable format.
Definition: EnumDef.php:130
const PARAM_DEPRECATED_VALUES
(array) Associative array of deprecated values.
Definition: EnumDef.php:49
sortEnumValues(string $name, array $values, array $settings, array $options)
Sort enum values for help/param info output.
Definition: EnumDef.php:192
getEnumValuesForHelp( $name, array $settings, array $options)
Return enum values formatted for the help message.
Definition: EnumDef.php:217
Base definition for ParamValidator types.
Definition: TypeDef.php:19
failureMessage( $code, array $data=null, $suffix=null)
Create a DataMessageValue representing a failure.
Definition: TypeDef.php:84
getEnumValues( $name, array $settings, array $options)
Get the values for enum-like parameters.
Definition: TypeDef.php:185
failure( $failure, $name, $value, array $settings, array $options, $fatal=true)
Record a failure message.
Definition: TypeDef.php:49