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