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

Collaboration diagram for Wikimedia\ParamValidator\ParamValidator:

[legend]

Public Member Functions
	__construct (Callbacks $callbacks, ObjectFactory $objectFactory, array $options=[])

	addTypeDef ( $name, $typeDef)
	Register a type handler.

	addTypeDefs (array $typeDefs)
	Register multiple type handlers.

	getTypeDef ( $type)
	Get the TypeDef for a type.

	getValue ( $name, $settings, array $options=[])
	Fetch and valiate a parameter value using a settings array.

	hasTypeDef ( $name)
	Test if a type is registered.

	knownTypes ()
	List known type names.

	normalizeSettings ( $settings)
	Normalize a parameter settings array.

	overrideTypeDef ( $name, $typeDef)
	Register a type handler, overriding any existing handler.

	validateValue ( $name, $value, $settings, array $options=[])
	Valiate a parameter value using a settings array.

Static Public Member Functions
static	explodeMultiValue ( $value, $limit)
	Split a multi-valued parameter string, like explode()

Public Attributes
const	ALL_DEFAULT_STRING = '*'
	Magic "all values" value when PARAM_ALL is true.

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.

const	PARAM_TYPE = 'param-type'
	(string\|array) Type of the parameter.

const	PARAM_REQUIRED = 'param-required'
	(bool) Indicate that the parameter is required.

const	PARAM_ISMULTI = 'param-ismulti'
	(bool) Indicate that the parameter is multi-valued.

const	PARAM_ISMULTI_LIMIT1 = 'param-ismulti-limit1'
	(int) Maximum number of multi-valued parameter values allowed

const	PARAM_ISMULTI_LIMIT2 = 'param-ismulti-limit2'
	(int) Maximum number of multi-valued parameter values allowed for users allowed high limits.

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.

const	PARAM_ALLOW_DUPLICATES = 'param-allow-duplicates'
	(bool) Allow the same value to be set more than once when PARAM_ISMULTI is true?

const	PARAM_SENSITIVE = 'param-sensitive'
	(bool) Indicate that the parameter's value should not be logged.

const	PARAM_DEPRECATED = 'param-deprecated'
	(bool) Indicate that a deprecated parameter was used.

const	PARAM_IGNORE_INVALID_VALUES = 'param-ignore-invalid-values'
	(bool) Whether to ignore invalid values.

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

Private Attributes
Callbacks	$callbacks

int	$ismultiLimit1
	Default values for PARAM_ISMULTI_LIMIT1.

int	$ismultiLimit2
	Default values for PARAM_ISMULTI_LIMIT2.

ObjectFactory	$objectFactory

TypeDef array[]	$typeDefs = []
	Map parameter type names to TypeDef objects or ObjectFactory specs.

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	$objectFactory	To turn specs into TypeDef objects
array	$options	Associative 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:

The Callbacks object for this ParamValidator instance.

Parameters

string	$name	Type name
TypeDef \| array	$typeDef	Type 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 $typeDefs Associative 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 $type Any 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	$name	Parameter name
array \| mixed	$settings	Default value or an array of settings using PARAM_* constants.
array	$options	Options array, passed through to the TypeDef and Callbacks.

Returns: mixed Validated parameter value

Exceptions

ValidationException if 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 $name Type 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 $settings Default 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	$name	Type name
TypeDef \| array \| null	$typeDef	As 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	$name	Parameter name
null \| mixed	$value	Parameter value
array \| mixed	$settings	Default value or an array of settings using PARAM_* constants.
array	$options	Options 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

ValidationException if the value is invalid

Definition at line 418 of file ParamValidator.php.

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

Member Data Documentation

◆ $callbacks

Callbacks Wikimedia\ParamValidator\ParamValidator::$callbacks

private

Definition at line 197 of file ParamValidator.php.

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

◆ $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

Definition at line 200 of file ParamValidator.php.

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

◆ $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:

includes/libs/ParamValidator/ParamValidator.php

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addTypeDef()

◆ addTypeDefs()

◆ explodeMultiValue()

◆ getTypeDef()

◆ getValue()

◆ hasTypeDef()

◆ knownTypes()

◆ normalizeSettings()

◆ overrideTypeDef()

◆ validateValue()

Member Data Documentation

◆ $callbacks

◆ $ismultiLimit1

◆ $ismultiLimit2

◆ $objectFactory

◆ $STANDARD_TYPES

◆ $typeDefs

◆ ALL_DEFAULT_STRING

◆ PARAM_ALL

◆ PARAM_ALLOW_DUPLICATES

◆ PARAM_DEFAULT

◆ PARAM_DEPRECATED

◆ PARAM_IGNORE_INVALID_VALUES

◆ PARAM_ISMULTI

◆ PARAM_ISMULTI_LIMIT1

◆ PARAM_ISMULTI_LIMIT2

◆ PARAM_REQUIRED

◆ PARAM_SENSITIVE

◆ PARAM_TYPE