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.

	checkSettings (string $name, $settings, array $options)
	Validate a parameter settings array.

	getHelpInfo ( $name, $settings, array $options)
	Describe parameter settings in human-readable format.

	getParamInfo ( $name, $settings, array $options)
	Describe parameter settings in a machine-readable format.

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

	getValue ( $name, $settings, array $options=[])
	Fetch and validate 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=[])
	Validate a parameter value using a settings array.

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

static	implodeMultiValue (array $value)
	Implode an array as a multi-valued parameter string, like implode()

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 failure code, 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_UNRECOGNIZED_VALUES = 'param-ignore-unrecognized-values'
	(bool) Whether to downgrade "badvalue" errors to non-fatal when validating multi-valued parameters.

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

Private Member Functions
	normalizeSettingsInternal ( $settings)
	Logic shared by normalizeSettings() and checkSettings()

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 42 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 221 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 267 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 248 of file ParamValidator.php.

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

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

◆ checkSettings()

Wikimedia\ParamValidator\ParamValidator::checkSettings	(	string	$name,
			$settings,
		array	$options
	)

Validate a parameter settings array.

This is intended for validation of parameter settings during unit or integration testing, and should implement strict checks.

The rest of the code should generally be more permissive.

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

array

'issues': (string[]) Errors detected in $settings, as English text. If the settings are valid, this will be the empty array.
'allowedKeys': (string[]) ParamValidator keys that are allowed in $settings.
'messages': (MessageValue[]) Messages to be checked for existence.

Definition at line 391 of file ParamValidator.php.

References $type, and Wikimedia\ParamValidator\ParamValidator\PARAM_TYPE.

◆ 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 828 of file ParamValidator.php.

◆ getHelpInfo()

Wikimedia\ParamValidator\ParamValidator::getHelpInfo	(		$name,
			$settings,
		array	$options
	)

Describe parameter settings in human-readable format.

Parameters

string	$name	Parameter name being described.
array \| mixed	$settings	Default value or an array of settings using PARAM_* constants.
array	$options	Options array.

Returns: MessageValue[]

Definition at line 741 of file ParamValidator.php.

◆ getParamInfo()

Wikimedia\ParamValidator\ParamValidator::getParamInfo	(		$name,
			$settings,
		array	$options
	)

Describe parameter settings in a machine-readable format.

Parameters

string	$name	Parameter name.
array \| mixed	$settings	Default value or an array of settings using PARAM_* constants.
array	$options	Options array.

Returns: array

Definition at line 682 of file ParamValidator.php.

◆ 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 314 of file ParamValidator.php.

References $type.

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

◆ getValue()

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

Fetch and validate 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. An additional option, 'is-default', will be set when the value comes from PARAM_DEFAULT.

Returns: mixed Validated parameter value

Exceptions

ValidationException if the value is invalid

Definition at line 514 of file ParamValidator.php.

◆ hasTypeDef()

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

Test if a type is registered.

Parameters

string $name Type name

Returns: bool

Definition at line 305 of file ParamValidator.php.

◆ implodeMultiValue()

static Wikimedia\ParamValidator\ParamValidator::implodeMultiValue ( array $value )

static

Implode an array as a multi-valued parameter string, like implode()

Parameters

array $value

Returns: string

Definition at line 849 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\EnumDef\stringifyValue().

◆ knownTypes()

Wikimedia\ParamValidator\ParamValidator::knownTypes ( )

List known type names.

Returns: string[]

Definition at line 238 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 362 of file ParamValidator.php.

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

◆ normalizeSettingsInternal()

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

private

Logic shared by normalizeSettings() and checkSettings()

Parameters

array | mixed $settings

Returns: array

Definition at line 340 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\PARAM_TYPE.

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

◆ 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 286 of file ParamValidator.php.

◆ validateValue()

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

Validate 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 566 of file ParamValidator.php.

References Wikimedia\ParamValidator\ValidationException\getFailureMessage(), and Wikimedia\Message\ParamType\PLAINTEXT.

Member Data Documentation

◆ $callbacks

Callbacks Wikimedia\ParamValidator\ParamValidator::$callbacks

private

Definition at line 198 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 207 of file ParamValidator.php.

◆ $ismultiLimit2

int Wikimedia\ParamValidator\ParamValidator::$ismultiLimit2

private

Default values for PARAM_ISMULTI_LIMIT2.

Definition at line 210 of file ParamValidator.php.

◆ $objectFactory

ObjectFactory Wikimedia\ParamValidator\ParamValidator::$objectFactory

private

Definition at line 201 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 ],
        'expiry' => [ 'class' => TypeDef\ExpiryDef::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 204 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.

◆ 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 137 of file ParamValidator.php.

◆ 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 145 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.

TypeDef::validate() will be informed when the default value was used by the presence of 'is-default' in $options.

Definition at line 68 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\UploadDef\checkSettings(), Wikimedia\ParamValidator\TypeDef\PresenceBooleanDef\getHelpInfo(), and Wikimedia\ParamValidator\TypeDef\PresenceBooleanDef\normalizeSettings().

◆ PARAM_DEPRECATED

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

(bool) Indicate that a deprecated parameter was used.

Failure codes: (non-fatal)

'param-deprecated': Always recorded when the parameter is used.

Definition at line 161 of file ParamValidator.php.

◆ PARAM_IGNORE_UNRECOGNIZED_VALUES

const Wikimedia\ParamValidator\ParamValidator::PARAM_IGNORE_UNRECOGNIZED_VALUES = 'param-ignore-unrecognized-values'

(bool) Whether to downgrade "badvalue" errors to non-fatal when validating multi-valued parameters.

See also: PARAM_ISMULTI

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 in 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.

Failure codes:

'toomanyvalues': More values were supplied than are allowed. See PARAM_ISMULTI_LIMIT1, PARAM_ISMULTI_LIMIT2, and constructor option 'ismultiLimits'. Data:
- 'limit': The limit currently in effect.
- 'lowlimit': The limit when high limits are not allowed.
- 'highlimit': The limit when high limits are allowed.
'unrecognizedvalues': Non-fatal. Invalid values were passed and PARAM_IGNORE_UNRECOGNIZED_VALUES was set. Data:
- 'values': The unrecognized values.

Definition at line 112 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

See also: PARAM_ISMULTI

Definition at line 119 of file ParamValidator.php.

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

See also: PARAM_ISMULTI

Definition at line 127 of file ParamValidator.php.

◆ PARAM_REQUIRED

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

(bool) Indicate that the parameter is required.

Failure codes:

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

Definition at line 84 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.

Failure codes: (non-fatal)

'param-sensitive': Always recorded when the parameter is used.

Definition at line 153 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\PasswordDef\checkSettings(), and 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 76 of file ParamValidator.php.

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 Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addTypeDef()

◆ addTypeDefs()

◆ checkSettings()

◆ explodeMultiValue()

◆ getHelpInfo()

◆ getParamInfo()

◆ getTypeDef()

◆ getValue()

◆ hasTypeDef()

◆ implodeMultiValue()

◆ knownTypes()

◆ normalizeSettings()

◆ normalizeSettingsInternal()

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

◆ PARAM_ISMULTI

◆ PARAM_ISMULTI_LIMIT1

◆ PARAM_ISMULTI_LIMIT2

◆ PARAM_REQUIRED

◆ PARAM_SENSITIVE

◆ PARAM_TYPE