Type definition for array structures, typically used for validating JSON request bodies. More...

Inherits Wikimedia\ParamValidator\TypeDef.

Collaboration diagram for MediaWiki\ParamValidator\TypeDef\ArrayDef:

[legend]

Public Member Functions
	stringifyValue ( $name, $value, array $settings, array $options)
	Convert a value to a string representation.

	supportsArrays ()
	Whether the value may be an array.

	validate ( $name, $value, array $settings, array $options)
	Validate the value.

Public Member Functions inherited from Wikimedia\ParamValidator\TypeDef
	__construct (Callbacks $callbacks)

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

	getEnumValues ( $name, array $settings, array $options)
	Get the values for enum-like parameters.

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

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

	getValue ( $name, array $settings, array $options)
	Get the value from the request.

	normalizeSettings (array $settings)
	Normalize a settings array.

Static Public Member Functions
static	makeListSchema ( $itemSchema)
	Returns a JSON Schema of type array, with the input schema for each array item.

static	makeMapSchema ( $entrySchema)
	Returns a JSON Schema of type object, with the input schema for each array item.

static	makeObjectSchema (array $required=[], array $optional=[], $additional=false)
	Returns a JSON Schema of type object, with properties defined by the function params.

Public Attributes
const	PARAM_SCHEMA = 'param-schema'
	(object) Schema settings.

Public Attributes inherited from Wikimedia\ParamValidator\TypeDef
const	OPT_ENFORCE_JSON_TYPES = 'enforce-json-types'
	Option that instructs TypeDefs to enforce the native type of parameter values, instead of allowing string values as input.

const	OPT_LOG_BAD_TYPES = 'log-bad-types'

Additional Inherited Members
Protected Member Functions inherited from Wikimedia\ParamValidator\TypeDef
	failIfNotString (string $name, $value, array $settings, array $options)
	Fails if $value is not a string.

	failure ( $failure, $name, $value, array $settings, array $options, $fatal=true)
	Record a failure message.

	failureMessage ( $code, ?array $data=null, $suffix=null)
	Create a DataMessageValue representing a failure.

	fatal ( $failure, $name, $value, array $settings, array $options)
	Throw a ValidationException.

Protected Attributes inherited from Wikimedia\ParamValidator\TypeDef
Callbacks	$callbacks

Detailed Description

Type definition for array structures, typically used for validating JSON request bodies.

Failure codes:

'notarray': The value is not an array.

Since: 1.42

Definition at line 21 of file ArrayDef.php.

Member Function Documentation

◆ makeListSchema()

static MediaWiki\ParamValidator\TypeDef\ArrayDef::makeListSchema ( $itemSchema )

static

Returns a JSON Schema of type array, with the input schema for each array item.

If $itemSchema is a string, it must be a valid JSON type, and all list entries will be validated to be of that type.

If $itemSchema is an array, it must represent a valid schema, and all list entries will be validated to be of that schema. Nested lists are supported, as are lists of maps and more complicated schemas.

Examples: A list of integers, like [ 1, 2, 3 ] ArrayDef::makeListSchema( "integer" ) A list of strings, where each value must be either "a" or "b", like [ "a", "a", "b", "b" ]

ArrayDef::makeListSchema( [ 'enum' => [ 'a', 'b' ] ] ) A list of lists of strings, like [ [ "foo", 'bar" ], [ "baz", "qux" ] ] ArrayDef::makeListSchema( ArrayDef::makeListSchema( "string" ) )

Since: 1.43

Parameters

array | string $itemSchema

Returns: array

Definition at line 107 of file ArrayDef.php.

◆ makeMapSchema()

static MediaWiki\ParamValidator\TypeDef\ArrayDef::makeMapSchema ( $entrySchema )

static

Returns a JSON Schema of type object, with the input schema for each array item.

If $entrySchema is a string, it must be a valid JSON type, and all map entries will be validated to be of that type.

If $entrySchema is an array, it must represent a valid schema, and all map entries will be validated to be of that schema. Nested maps are supported, as are maps of lists and more complicated schemas

Examples: A map of integers, like [ 'key1' => 1, 'key2' => 2, 'key3' => 3 ] ArrayDef::makeMapSchema( "integer" ) A map of where each value must be 0 or 1, like [ 'key1' => 1, 'key2' => 1, 'key3' => 0 ] ArrayDef::makeMapSchema( [ 'enum' => [ 0, 1 ] ] ) A map of maps, like [ 'k1' => [ 'k2' => 'a' ], 'k3' => [ 'k4' => 'b', 'k5' => 'c' ] ] ArrayDef::makeMapSchema( ArrayDef::makeMapSchema( "string" ) )

Since: 1.43

Parameters

array | string $entrySchema

Returns: array

Definition at line 138 of file ArrayDef.php.

◆ makeObjectSchema()

static MediaWiki\ParamValidator\TypeDef\ArrayDef::makeObjectSchema	(	array	$required = [],
		array	$optional = [],
			$additional = false )

static

Returns a JSON Schema of type object, with properties defined by the function params.

Any input schemas must either be a string corresponding to valid JSON types, or valid schemas. Nested schemas are supported.

Examples: An object with required parameters "a" and "b", where "a" must be an integer and "b" can have one of the values "x", "y", or "z", no optional parameters, and additional parameters are disallowed: ArrayDef::makeObjectSchema( [ 'a' => 'integer', 'b' => [ 'enum' => [ 'x', 'y', 'z' ] ] ] ) The same object, but parameter "b" is optional: ArrayDef::makeObjectSchema( [ 'a' => 'integer' ], [ 'b' => [ 'enum' => [ 'x', 'y', 'z' ] ] ] ) An object with no required properties, an optional property "a" of type string, with arbitrary additional properties allowed (effectively, an arbitrary object, but if "a" is present, it must be a string): ArrayDef::makeObjectSchema( [ ], [ 'a' => 'string' ], true )

Since: 1.43

Parameters

array	$required	properties that are required to be present, as name/schema pairs
array	$optional	properties that may or may not be present, as name/schema pairs
array \| bool \| string	$additional	schema additional properties must match, or false to disallow additional properties, or true to allow arbitrary additional properties

Returns: array

Definition at line 171 of file ArrayDef.php.

◆ stringifyValue()

MediaWiki\ParamValidator\TypeDef\ArrayDef::stringifyValue	(		$name,
			$value,
		array	$settings,
		array	$options )

Convert a value to a string representation.

This is intended as the inverse of getValue() and validate(): this should accept anything returned by those methods or expected to be used as PARAM_DEFAULT, and if the string from this method is passed in as client input or PARAM_DEFAULT it should give equivalent output from validate().

Parameters

string	$name	Parameter name being converted.
mixed	$value	Parameter value being converted. Do not pass null.
array	$settings	Parameter settings array.
array	$options	Options array.

Returns: string|null Return null if there is no representation of $value reasonably satisfying the description given.

Reimplemented from Wikimedia\ParamValidator\TypeDef.

Definition at line 75 of file ArrayDef.php.

◆ supportsArrays()

MediaWiki\ParamValidator\TypeDef\ArrayDef::supportsArrays ( )

Whether the value may be an array.

Note that this is different from multi-value. This should only return true if each value can be an array.

Since: 1.41

Stability: stable: to override

Returns: bool

Reimplemented from Wikimedia\ParamValidator\TypeDef.

Definition at line 29 of file ArrayDef.php.

◆ validate()

MediaWiki\ParamValidator\TypeDef\ArrayDef::validate	(		$name,
			$value,
		array	$settings,
		array	$options )

Validate the value.

When ParamValidator is processing a multi-valued parameter, this will be called once for each of the supplied values. Which may mean zero calls.

When getValue() returned null, this will not be called.

Parameters

string	$name	Parameter name being validated.
mixed	$value	Value to validate, from getValue().
array	$settings	Parameter settings array.
array	$options	Options array. Note the following values that may be set by ParamValidator: is-default: (bool) If present and true, the value was taken from PARAM_DEFAULT rather that being supplied by the client. values-list: (string[]) If defined, values of a multi-valued parameter are being processed (and this array holds the full set of values).

Returns: mixed Validated value

Exceptions

ValidationException if the value is invalid

Reimplemented from Wikimedia\ParamValidator\TypeDef.

Definition at line 33 of file ArrayDef.php.

References Wikimedia\ParamValidator\TypeDef\failure(), and MediaWiki\ParamValidator\TypeDef\ArrayDef\PARAM_SCHEMA.

Member Data Documentation

◆ PARAM_SCHEMA

const MediaWiki\ParamValidator\TypeDef\ArrayDef::PARAM_SCHEMA = 'param-schema'

(object) Schema settings.

Definition at line 27 of file ArrayDef.php.

Referenced by MediaWiki\ParamValidator\TypeDef\ArrayDef\validate().

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

includes/ParamValidator/TypeDef/ArrayDef.php

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ makeListSchema()

◆ makeMapSchema()

◆ makeObjectSchema()

◆ stringifyValue()

◆ supportsArrays()

◆ validate()

Member Data Documentation

◆ PARAM_SCHEMA