MediaWiki  master
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...
 
 getHelpInfo ( $name, $settings, array $options)
 Describe parameter settings in human-readable format. More...
 
 getParamInfo ( $name, $settings, array $options)
 Describe parameter settings in a machine-readable format. 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...
 
static implodeMultiValue (array $value)
 Implode an array as a multi-valued parameter string, like implode() 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 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. 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

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$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 218 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 264 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 245 of file ParamValidator.php.

References 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 678 of file ParamValidator.php.

◆ getHelpInfo()

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

Describe parameter settings in human-readable format.

Parameters
string$nameParameter name being described.
array | mixed$settingsDefault value or an array of settings using PARAM_* constants.
array$optionsOptions array.
Returns
MessageValue[]

Definition at line 591 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\$ismultiLimit1, Wikimedia\ParamValidator\ParamValidator\getTypeDef(), Wikimedia\Message\MessageValue\new(), and Wikimedia\ParamValidator\ParamValidator\normalizeSettings().

◆ getParamInfo()

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

Describe parameter settings in a machine-readable format.

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

Definition at line 532 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\$ismultiLimit1, Wikimedia\ParamValidator\ParamValidator\getTypeDef(), and Wikimedia\ParamValidator\ParamValidator\normalizeSettings().

◆ getTypeDef()

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

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

References Wikimedia\ParamValidator\ParamValidator\getTypeDef(), Wikimedia\Message\DataMessageValue\new(), Wikimedia\ParamValidator\ParamValidator\normalizeSettings(), 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 302 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 699 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 235 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 338 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\getTypeDef().

Referenced by Wikimedia\ParamValidator\ParamValidator\getHelpInfo(), Wikimedia\ParamValidator\ParamValidator\getParamInfo(), 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 283 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\getTypeDef(), Wikimedia\Message\DataMessageValue\new(), Wikimedia\ParamValidator\ParamValidator\normalizeSettings(), and Wikimedia\Message\ParamType\PLAINTEXT.

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

Member Data Documentation

◆ $callbacks

Callbacks Wikimedia\ParamValidator\ParamValidator::$callbacks
private

◆ $ismultiLimit1

int Wikimedia\ParamValidator\ParamValidator::$ismultiLimit1
private

◆ $ismultiLimit2

int Wikimedia\ParamValidator\ParamValidator::$ismultiLimit2
private

Default values for PARAM_ISMULTI_LIMIT2.

Definition at line 207 of file ParamValidator.php.

◆ $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 174 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 201 of file ParamValidator.php.

◆ ALL_DEFAULT_STRING

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

Magic "all values" value when PARAM_ALL is true.

Definition at line 171 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 132 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 140 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 63 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\PresenceBooleanDef\getHelpInfo().

◆ 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 156 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 failures are considered fatal or non-fatal. The default is false.

See also
PARAM_ISMULTI

Definition at line 166 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_INVALID_VALUES was set. Data:
    • 'values': The unrecognized values.

Definition at line 107 of file ParamValidator.php.

Referenced by Wikimedia\ParamValidator\TypeDef\IntegerDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\BooleanDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\FloatDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\TimestampDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\EnumDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\NumericDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\PresenceBooleanDef\normalizeSettings(), and Wikimedia\ParamValidator\TypeDef\LimitDef\normalizeSettings().

◆ 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 114 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 122 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 79 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 148 of file ParamValidator.php.

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

◆ PARAM_TYPE

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

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