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...
 
 checkSettings (string $name, $settings, array $options)
 Validate a parameter settings array. 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 validate 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=[])
 Validate 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_UNRECOGNIZED_VALUES = 'param-ignore-unrecognized-values'
 (bool) Whether to downgrade "badvalue" errors to non-fatal when validating multi-valued parameters. 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 Member Functions

 normalizeSettingsInternal ( $settings)
 Logic shared by normalizeSettings() and checkSettings() 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 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 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:

Parameters
string$nameType name
TypeDef | array$typeDefType 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$typeDefsAssociative 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$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
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 Wikimedia\ParamValidator\ParamValidator\$ismultiLimit1, Wikimedia\ParamValidator\ParamValidator\$ismultiLimit2, $type, Wikimedia\ParamValidator\ParamValidator\ALL_DEFAULT_STRING, Wikimedia\ParamValidator\ValidationException\getFailureMessage(), Wikimedia\ParamValidator\ParamValidator\getTypeDef(), Wikimedia\ParamValidator\ParamValidator\normalizeSettingsInternal(), Wikimedia\ParamValidator\ParamValidator\PARAM_ALL, Wikimedia\ParamValidator\ParamValidator\PARAM_ALLOW_DUPLICATES, Wikimedia\ParamValidator\ParamValidator\PARAM_DEFAULT, Wikimedia\ParamValidator\ParamValidator\PARAM_DEPRECATED, Wikimedia\ParamValidator\ParamValidator\PARAM_IGNORE_UNRECOGNIZED_VALUES, Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI, Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI_LIMIT1, Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI_LIMIT2, Wikimedia\ParamValidator\ParamValidator\PARAM_REQUIRED, Wikimedia\ParamValidator\ParamValidator\PARAM_SENSITIVE, Wikimedia\ParamValidator\ParamValidator\PARAM_TYPE, and Wikimedia\ParamValidator\ParamValidator\validateValue().

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

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

◆ getHelpInfo()

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

◆ getParamInfo()

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

◆ getTypeDef()

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

◆ getValue()

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

Fetch and validate 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.
  • An additional option, 'is-default', will be set when the value comes from PARAM_DEFAULT.
Returns
mixed Validated parameter value
Exceptions
ValidationExceptionif the value is invalid

Definition at line 514 of file ParamValidator.php.

References Wikimedia\ParamValidator\ParamValidator\getTypeDef(), Wikimedia\Message\DataMessageValue\new(), 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 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(), and Wikimedia\ParamValidator\ParamValidator\validateValue().

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

◆ normalizeSettingsInternal()

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

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

References Wikimedia\ParamValidator\ParamValidator\$ismultiLimit1, Wikimedia\ParamValidator\ParamValidator\ALL_DEFAULT_STRING, Wikimedia\ParamValidator\ParamValidator\explodeMultiValue(), Wikimedia\ParamValidator\ValidationException\getFailureMessage(), Wikimedia\ParamValidator\ParamValidator\getTypeDef(), Wikimedia\ParamValidator\ParamValidator\implodeMultiValue(), Wikimedia\Message\DataMessageValue\new(), Wikimedia\ParamValidator\ParamValidator\normalizeSettings(), Wikimedia\ParamValidator\ParamValidator\PARAM_ALL, Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI_LIMIT1, and Wikimedia\Message\ParamType\PLAINTEXT.

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

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

◆ $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 ],
'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 = '*'

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

Referenced by Wikimedia\ParamValidator\ParamValidator\checkSettings(), Wikimedia\ParamValidator\ParamValidator\TypeDef\NamespaceDef\checkSettings(), Wikimedia\ParamValidator\ParamValidator\getHelpInfo(), Wikimedia\ParamValidator\ParamValidator\getParamInfo(), Wikimedia\ParamValidator\ParamValidator\TypeDef\NamespaceDef\normalizeSettings(), and 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 145 of file ParamValidator.php.

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

◆ PARAM_DEFAULT

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

Referenced by Wikimedia\ParamValidator\ParamValidator\checkSettings(), and Wikimedia\ParamValidator\ParamValidator\getHelpInfo().

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

Referenced by Wikimedia\ParamValidator\ParamValidator\checkSettings(), and MediaWiki\Api\Validator\ApiParamValidator\normalizeSettings().

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

Referenced by MediaWiki\Api\Validator\ApiParamValidator\checkSettings(), Wikimedia\ParamValidator\ParamValidator\checkSettings(), Wikimedia\ParamValidator\TypeDef\LimitDef\checkSettings(), Wikimedia\ParamValidator\TypeDef\PresenceBooleanDef\checkSettings(), Wikimedia\ParamValidator\TypeDef\UploadDef\checkSettings(), Wikimedia\ParamValidator\ParamValidator\TypeDef\NamespaceDef\checkSettings(), Wikimedia\ParamValidator\ParamValidator\TypeDef\UserDef\checkSettings(), Wikimedia\ParamValidator\ParamValidator\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\BooleanDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\EnumDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\ExpiryDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\FloatDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\IntegerDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\NumericDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\TimestampDef\getHelpInfo(), Wikimedia\ParamValidator\ParamValidator\TypeDef\UserDef\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\LimitDef\normalizeSettings(), Wikimedia\ParamValidator\TypeDef\PresenceBooleanDef\normalizeSettings(), and Wikimedia\ParamValidator\ParamValidator\TypeDef\NamespaceDef\normalizeSettings().

◆ PARAM_ISMULTI_LIMIT1

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

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

Referenced by Wikimedia\ParamValidator\ParamValidator\checkSettings(), and Wikimedia\ParamValidator\ParamValidator\TypeDef\UserDef\checkSettings().

◆ 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\ParamValidator\checkSettings(), Wikimedia\ParamValidator\TypeDef\StringDef\checkSettings(), Wikimedia\ParamValidator\ParamValidator\getHelpInfo(), Wikimedia\ParamValidator\TypeDef\StringDef\validate(), and MediaWiki\Rest\Validator\JsonBodyValidator\validateBody().

◆ 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\ParamValidator\checkSettings(), Wikimedia\ParamValidator\TypeDef\PasswordDef\checkSettings(), and Wikimedia\ParamValidator\TypeDef\PasswordDef\normalizeSettings().

◆ PARAM_TYPE


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