MediaWiki  1.34.0
Wikimedia\ParamValidator\ParamValidator Class Reference

Service for formatting and validating API parameters. More...

Collaboration diagram for Wikimedia\ParamValidator\ParamValidator:

Public Member Functions

 __construct (Callbacks $callbacks, ObjectFactory $objectFactory, array $options=[])
 
 addTypeDef ( $name, $typeDef)
 Register a type handler. More...
 
 addTypeDefs (array $typeDefs)
 Register multiple type handlers. More...
 
 getTypeDef ( $type)
 Get the TypeDef for a type. More...
 
 getValue ( $name, $settings, array $options=[])
 Fetch and valiate a parameter value using a settings array. More...
 
 hasTypeDef ( $name)
 Test if a type is registered. More...
 
 knownTypes ()
 List known type names. More...
 
 normalizeSettings ( $settings)
 Normalize a parameter settings array. More...
 
 overrideTypeDef ( $name, $typeDef)
 Register a type handler, overriding any existing handler. More...
 
 validateValue ( $name, $value, $settings, array $options=[])
 Valiate a parameter value using a settings array. More...
 

Static Public Member Functions

static explodeMultiValue ( $value, $limit)
 Split a multi-valued parameter string, like explode() More...
 

Public Attributes

const ALL_DEFAULT_STRING = '*'
 Magic "all values" value when PARAM_ALL is true. More...
 
Constants for parameter settings arrays

These constants are keys in the settings array that define how the parameters coming in from the request are to be interpreted.

If a constant is associated with a ValidationException, the failure code and data are described. ValidationExceptions are typically thrown, but those indicated as "non-fatal" are instead passed to Callbacks::recordCondition().

Additional constants may be defined by TypeDef subclasses, or by other libraries for controlling things like auto-generated parameter documentation. For purposes of namespacing the constants, the values of all constants defined by this library begin with 'param-'.

const PARAM_DEFAULT = 'param-default'
 (mixed) Default value of the parameter. More...
 
const PARAM_TYPE = 'param-type'
 (string|array) Type of the parameter. More...
 
const PARAM_REQUIRED = 'param-required'
 (bool) Indicate that the parameter is required. More...
 
const PARAM_ISMULTI = 'param-ismulti'
 (bool) Indicate that the parameter is multi-valued. More...
 
const PARAM_ISMULTI_LIMIT1 = 'param-ismulti-limit1'
 (int) Maximum number of multi-valued parameter values allowed More...
 
const PARAM_ISMULTI_LIMIT2 = 'param-ismulti-limit2'
 (int) Maximum number of multi-valued parameter values allowed for users allowed high limits. More...
 
const PARAM_ALL = 'param-all'
 (bool|string) Whether a magic "all values" value exists for multi-valued enumerated types, and if so what that value is. More...
 
const PARAM_ALLOW_DUPLICATES = 'param-allow-duplicates'
 (bool) Allow the same value to be set more than once when PARAM_ISMULTI is true? More...
 
const PARAM_SENSITIVE = 'param-sensitive'
 (bool) Indicate that the parameter's value should not be logged. More...
 
const PARAM_DEPRECATED = 'param-deprecated'
 (bool) Indicate that a deprecated parameter was used. More...
 
const PARAM_IGNORE_INVALID_VALUES = 'param-ignore-invalid-values'
 (bool) Whether to ignore invalid values. More...
 

Static Public Attributes

static $STANDARD_TYPES
 A list of standard type names and types that may be passed as $typeDefs to __construct(). More...
 

Private Attributes

Callbacks $callbacks
 
int $ismultiLimit1
 Default values for PARAM_ISMULTI_LIMIT1. More...
 
int $ismultiLimit2
 Default values for PARAM_ISMULTI_LIMIT2. More...
 
ObjectFactory $objectFactory
 
TypeDef array[] $typeDefs = []
 Map parameter type names to TypeDef objects or ObjectFactory specs. More...
 

Detailed Description

Service for formatting and validating API parameters.

A settings array is simply an array with keys being the relevant PARAM_* constants from this class, TypeDef, and its subclasses.

As a general overview of the architecture here:

  • ParamValidator handles some general validation of the parameter, then hands off to a TypeDef subclass to validate the specific representation based on the parameter's type.
  • TypeDef subclasses handle conversion between the string representation submitted by the client and the output PHP data types, validating that the strings are valid representations of the intended type as they do so.
  • ValidationException is used to report fatal errors in the validation back to the caller, since the return value represents the successful result of the validation and might be any type or class.
  • The Callbacks interface allows ParamValidator to reach out and fetch data it needs to perform the validation. Currently that includes:
    • Fetching the value of the parameter being validated (largely since a generic caller cannot know whether it needs to fetch a string from $_GET/$_POST or an array from $_FILES).
    • Reporting of non-fatal warnings back to the caller.
    • Fetching the "high limits" flag when necessary, to avoid the need for loading the user unnecessarily.
Since
1.34 @unstable

Definition at line 38 of file ParamValidator.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\ParamValidator\ParamValidator::__construct ( Callbacks  $callbacks,
ObjectFactory  $objectFactory,
array  $options = [] 
)
Parameters
Callbacks$callbacks
ObjectFactory$objectFactoryTo turn specs into TypeDef objects
array$optionsAssociative array of additional settings
  • 'typeDefs': (array) As for addTypeDefs(). If omitted, self::$STANDARD_TYPES will be used. Pass an empty array if you want to start with no registered types.
  • 'ismultiLimits': (int[]) Two ints, being the default values for PARAM_ISMULTI_LIMIT1 and PARAM_ISMULTI_LIMIT2. If not given, defaults to [ 50, 500 ].

Definition at line 220 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\$callbacks, Wikimedia\ParamValidator\ParamValidator\$objectFactory, and Wikimedia\ParamValidator\ParamValidator\addTypeDefs().

Member Function Documentation

◆ addTypeDef()

Wikimedia\ParamValidator\ParamValidator::addTypeDef (   $name,
  $typeDef 
)

Register a type handler.

To allow code to omit PARAM_TYPE in settings arrays to derive the type from PARAM_DEFAULT, it is strongly recommended that the following types be registered: "boolean", "integer", "double", "string", "NULL", and "enum".

When using ObjectFactory specs, the following extra arguments are passed:

Parameters
string$nameType name
TypeDef | array$typeDefType handler or ObjectFactory spec to create one.

Definition at line 266 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\ParamValidator\addTypeDefs().

◆ addTypeDefs()

Wikimedia\ParamValidator\ParamValidator::addTypeDefs ( array  $typeDefs)

Register multiple type handlers.

See also
addTypeDef()
Parameters
array$typeDefsAssociative array mapping $name to $typeDef.

Definition at line 247 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\$typeDefs, and Wikimedia\ParamValidator\ParamValidator\addTypeDef().

Referenced by Wikimedia\ParamValidator\ParamValidator\__construct().

◆ explodeMultiValue()

static Wikimedia\ParamValidator\ParamValidator::explodeMultiValue (   $value,
  $limit 
)
static

Split a multi-valued parameter string, like explode()

Note that, unlike explode(), this will return an empty array when given an empty string.

Parameters
string$value
int$limit
Returns
string[]

Definition at line 508 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\EnumDef\validate(), and Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ getTypeDef()

Wikimedia\ParamValidator\ParamValidator::getTypeDef (   $type)

Get the TypeDef for a type.

Parameters
string | array$typeAny array is considered equivalent to the string "enum".
Returns
TypeDef|null

Definition at line 313 of file ParamValidator.php.

References $type.

Referenced by Wikimedia\ParamValidator\ParamValidator\getValue(), Wikimedia\ParamValidator\ParamValidator\normalizeSettings(), and Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ getValue()

Wikimedia\ParamValidator\ParamValidator::getValue (   $name,
  $settings,
array  $options = [] 
)

Fetch and valiate a parameter value using a settings array.

Parameters
string$nameParameter name
array | mixed$settingsDefault value or an array of settings using PARAM_* constants.
array$optionsOptions array, passed through to the TypeDef and Callbacks.
Returns
mixed Validated parameter value
Exceptions
ValidationExceptionif the value is invalid

Definition at line 371 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\getTypeDef(), Wikimedia\ParamValidator\ParamValidator\normalizeSettings(), Wikimedia\ParamValidator\ParamValidator\PARAM_DEFAULT, and Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ hasTypeDef()

Wikimedia\ParamValidator\ParamValidator::hasTypeDef (   $name)

Test if a type is registered.

Parameters
string$nameType name
Returns
bool

Definition at line 304 of file ParamValidator.php.

◆ knownTypes()

Wikimedia\ParamValidator\ParamValidator::knownTypes ( )

List known type names.

Returns
string[]

Definition at line 237 of file ParamValidator.php.

◆ normalizeSettings()

Wikimedia\ParamValidator\ParamValidator::normalizeSettings (   $settings)

Normalize a parameter settings array.

Parameters
array | mixed$settingsDefault value or an array of settings using PARAM_* constants.
Returns
array

Definition at line 340 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\getTypeDef(), and Wikimedia\ParamValidator\ParamValidator\PARAM_TYPE.

Referenced by Wikimedia\ParamValidator\ParamValidator\getValue(), and Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ overrideTypeDef()

Wikimedia\ParamValidator\ParamValidator::overrideTypeDef (   $name,
  $typeDef 
)

Register a type handler, overriding any existing handler.

See also
addTypeDef
Parameters
string$nameType name
TypeDef | array | null$typeDefAs for addTypeDef, or null to unregister a type.

Definition at line 285 of file ParamValidator.php.

◆ validateValue()

Wikimedia\ParamValidator\ParamValidator::validateValue (   $name,
  $value,
  $settings,
array  $options = [] 
)

Valiate a parameter value using a settings array.

Parameters
string$nameParameter name
null | mixed$valueParameter value
array | mixed$settingsDefault value or an array of settings using PARAM_* constants.
array$optionsOptions array, passed through to the TypeDef and Callbacks.
  • An additional option, 'values-list', will be set when processing the values of a multi-valued parameter.
Returns
mixed Validated parameter value(s)
Exceptions
ValidationExceptionif the value is invalid

Definition at line 418 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\$ismultiLimit1, Wikimedia\ParamValidator\ParamValidator\$ismultiLimit2, Wikimedia\ParamValidator\ParamValidator\ALL_DEFAULT_STRING, Wikimedia\ParamValidator\ParamValidator\explodeMultiValue(), Wikimedia\ParamValidator\ParamValidator\getTypeDef(), Wikimedia\ParamValidator\ParamValidator\normalizeSettings(), Wikimedia\ParamValidator\ParamValidator\PARAM_ALL, Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI_LIMIT1, and Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI_LIMIT2.

Referenced by Wikimedia\ParamValidator\ParamValidator\getValue().

Member Data Documentation

◆ $callbacks

Callbacks Wikimedia\ParamValidator\ParamValidator::$callbacks
private

◆ $ismultiLimit1

int Wikimedia\ParamValidator\ParamValidator::$ismultiLimit1
private

Default values for PARAM_ISMULTI_LIMIT1.

Definition at line 206 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ $ismultiLimit2

int Wikimedia\ParamValidator\ParamValidator::$ismultiLimit2
private

Default values for PARAM_ISMULTI_LIMIT2.

Definition at line 209 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ $objectFactory

ObjectFactory Wikimedia\ParamValidator\ParamValidator::$objectFactory
private

◆ $STANDARD_TYPES

Wikimedia\ParamValidator\ParamValidator::$STANDARD_TYPES
static
Initial value:
= [
'boolean' => [ 'class' => TypeDef\BooleanDef::class ],
'checkbox' => [ 'class' => TypeDef\PresenceBooleanDef::class ],
'integer' => [ 'class' => TypeDef\IntegerDef::class ],
'limit' => [ 'class' => TypeDef\LimitDef::class ],
'float' => [ 'class' => TypeDef\FloatDef::class ],
'double' => [ 'class' => TypeDef\FloatDef::class ],
'string' => [ 'class' => TypeDef\StringDef::class ],
'password' => [ 'class' => TypeDef\PasswordDef::class ],
'NULL' => [
'class' => TypeDef\StringDef::class,
'args' => [ [
'allowEmptyWhenRequired' => true,
] ],
],
'timestamp' => [ 'class' => TypeDef\TimestampDef::class ],
'upload' => [ 'class' => TypeDef\UploadDef::class ],
'enum' => [ 'class' => TypeDef\EnumDef::class ],
]

A list of standard type names and types that may be passed as $typeDefs to __construct().

Definition at line 176 of file ParamValidator.php.

◆ $typeDefs

TypeDef array [] Wikimedia\ParamValidator\ParamValidator::$typeDefs = []
private

Map parameter type names to TypeDef objects or ObjectFactory specs.

Definition at line 203 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\ParamValidator\addTypeDefs().

◆ ALL_DEFAULT_STRING

const Wikimedia\ParamValidator\ParamValidator::ALL_DEFAULT_STRING = '*'

Magic "all values" value when PARAM_ALL is true.

Definition at line 173 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ PARAM_ALL

const Wikimedia\ParamValidator\ParamValidator::PARAM_ALL = 'param-all'

(bool|string) Whether a magic "all values" value exists for multi-valued enumerated types, and if so what that value is.

When PARAM_TYPE has a defined set of values and PARAM_ISMULTI is true, this allows for an asterisk ('*') to be passed in place of a pipe-separated list of every possible value. If a string is set, it will be used in place of the asterisk.

Definition at line 136 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ PARAM_ALLOW_DUPLICATES

const Wikimedia\ParamValidator\ParamValidator::PARAM_ALLOW_DUPLICATES = 'param-allow-duplicates'

(bool) Allow the same value to be set more than once when PARAM_ISMULTI is true?

If not truthy, the set of values will be passed through array_values( array_unique() ). The default is falsey.

Definition at line 144 of file ParamValidator.php.

◆ PARAM_DEFAULT

const Wikimedia\ParamValidator\ParamValidator::PARAM_DEFAULT = 'param-default'

(mixed) Default value of the parameter.

If omitted, null is the default.

Definition at line 59 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\describeSettings(), and Wikimedia\ParamValidator\ParamValidator\getValue().

◆ PARAM_DEPRECATED

const Wikimedia\ParamValidator\ParamValidator::PARAM_DEPRECATED = 'param-deprecated'

(bool) Indicate that a deprecated parameter was used.

ValidationException codes: (non-fatal)

  • 'param-deprecated': Always recorded.

Definition at line 160 of file ParamValidator.php.

◆ PARAM_IGNORE_INVALID_VALUES

const Wikimedia\ParamValidator\ParamValidator::PARAM_IGNORE_INVALID_VALUES = 'param-ignore-invalid-values'

(bool) Whether to ignore invalid values.

This controls whether certain ValidationExceptions are considered fatal or non-fatal. The default is false.

Definition at line 168 of file ParamValidator.php.

◆ PARAM_ISMULTI

const Wikimedia\ParamValidator\ParamValidator::PARAM_ISMULTI = 'param-ismulti'

(bool) Indicate that the parameter is multi-valued.

A multi-valued parameter may be submitted in one of several formats. All of the following result a value of ‘[ 'a’, 'b', 'c' ]`.

  • "a|b|c", i.e. pipe-separated.
  • "\\x1Fa\\x1Fb\\x1Fc", i.e. separated by U+001F, with a signalling U+001F at the start.
  • As a string[], e.g. from a query string like "foo[]=a&foo[]=b&foo[]=c".

Each of the multiple values is passed individually to the TypeDef. $options will contain a 'values-list' key holding the entire list.

By default duplicates are removed from the resulting parameter list. Use PARAM_ALLOW_DUPLICATES to override that behavior.

ValidationException codes:

  • 'toomanyvalues': More values were supplied than are allowed. See PARAM_ISMULTI_LIMIT1, PARAM_ISMULTI_LIMIT2, and constructor option 'ismultiLimits'. Data:
    • 'limit': The limit that was exceeded.
  • 'unrecognizedvalues': Non-fatal. Invalid values were passed and PARAM_IGNORE_INVALID_VALUES was set. Data:
    • 'values': The unrecognized values.

Definition at line 101 of file ParamValidator.php.

◆ PARAM_ISMULTI_LIMIT1

const Wikimedia\ParamValidator\ParamValidator::PARAM_ISMULTI_LIMIT1 = 'param-ismulti-limit1'

(int) Maximum number of multi-valued parameter values allowed

PARAM_ISMULTI_LIMIT1 is the normal limit, and PARAM_ISMULTI_LIMIT2 is the limit when useHighLimits() returns true.

ValidationException codes:

  • 'toomanyvalues': The limit was exceeded. Data:
    • 'limit': The limit that was exceeded.

Definition at line 113 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ PARAM_ISMULTI_LIMIT2

const Wikimedia\ParamValidator\ParamValidator::PARAM_ISMULTI_LIMIT2 = 'param-ismulti-limit2'

(int) Maximum number of multi-valued parameter values allowed for users allowed high limits.

PARAM_ISMULTI_LIMIT1 is the normal limit, and PARAM_ISMULTI_LIMIT2 is the limit when useHighLimits() returns true.

ValidationException codes:

  • 'toomanyvalues': The limit was exceeded. Data:
    • 'limit': The limit that was exceeded.

Definition at line 126 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\ParamValidator\validateValue().

◆ PARAM_REQUIRED

const Wikimedia\ParamValidator\ParamValidator::PARAM_REQUIRED = 'param-required'

(bool) Indicate that the parameter is required.

ValidationException codes:

  • 'missingparam': The parameter is omitted/empty (and no default was set). No data.

Definition at line 75 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\StringDef\validate().

◆ PARAM_SENSITIVE

const Wikimedia\ParamValidator\ParamValidator::PARAM_SENSITIVE = 'param-sensitive'

(bool) Indicate that the parameter's value should not be logged.

ValidationException codes: (non-fatal)

  • 'param-sensitive': Always recorded.

Definition at line 152 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\PasswordDef\normalizeSettings().

◆ PARAM_TYPE

const Wikimedia\ParamValidator\ParamValidator::PARAM_TYPE = 'param-type'

(string|array) Type of the parameter.

Must be a registered type or an array of enumerated values (in which case the "enum" type must be registered). If omitted, the default is the PHP type of the default value (see PARAM_DEFAULT).

Definition at line 67 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\EnumDef\getEnumValues(), and Wikimedia\ParamValidator\ParamValidator\normalizeSettings().


The documentation for this class was generated from the following file: