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