MediaWiki REL1_37
EnumDef.php
Go to the documentation of this file.
1<?php
2
4
14
32class 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.
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
const COMMA
A comma-separated list.
Definition ListType.php:11
Value object representing a message parameter that consists of a list of values.
Value object representing a message for i18n.
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:85
Value object representing a message parameter holding a single value.
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