RequestPayload
Provides field registration, magic accessors, validation and serialization for API request objects.
Used by ApiBase. Fields are declared with Field(), QueryParam() and RouteParam(), registered via initFields(), then read/written through PHP magic accessors and serialized into the JSON body, query string and URI route parameters of an outgoing request.
Table of Contents
Properties
- $payload : array<string|int, mixed>
Methods
- __get() : mixed
- Magic getter returning a registered field's current value.
- __set() : void
- Magic setter assigning a value to a registered field.
- details() : string
- Build a human-readable, multi-line description of every registered field.
- Field() : array<string|int, mixed>
- Define a request body (JSON) field descriptor.
- initFields() : void
- Register a set of field descriptors on this request.
- json() : array<string|int, mixed>
- Collect the registered body fields as a name/value map for the JSON request body.
- query() : array<string|int, mixed>
- Collect the registered query parameters as a name/value map for the query string.
- QueryParam() : array<string|int, mixed>
- Define a query-string parameter descriptor.
- route() : array<string|int, mixed>
- Collect the registered route parameters as a name/value map for URI substitution.
- RouteParam() : array<string|int, mixed>
- Define a URI route parameter descriptor.
- validate() : void
- Ensure every required field has been assigned a value.
Properties
$payload
protected
array<string|int, mixed>
$payload
= []
Methods
__get()
Magic getter returning a registered field's current value.
public
__get(string $name) : mixed
Parameters
- $name : string
-
The field name.
Tags
Return values
mixed —The current value of the field.
__set()
Magic setter assigning a value to a registered field.
public
__set(string $name, mixed $value) : void
Parameters
- $name : string
-
The field name.
- $value : mixed
-
The value to assign.
Tags
details()
Build a human-readable, multi-line description of every registered field.
public
details() : string
Return values
string —One line per field listing its name, type, required/optional status and description.
Field()
Define a request body (JSON) field descriptor.
public
static Field(string $name, string $vType[, bool $required = false ][, mixed $default = null ][, string $desc = "" ]) : array<string|int, mixed>
Parameters
- $name : string
-
The field name as sent in the request body.
- $vType : string
-
The value type (e.g.
string,integer,boolean). - $required : bool = false
-
Whether the field must be set before the request is sent. Defaults to false.
- $default : mixed = null
-
The default value for the field. Defaults to null.
- $desc : string = ""
-
A human-readable description of the field. Defaults to an empty string.
Return values
array<string|int, mixed> —The field descriptor.
initFields()
Register a set of field descriptors on this request.
public
initFields([array<string|int, mixed> $fields = [] ]) : void
Parameters
- $fields : array<string|int, mixed> = []
-
A list of descriptors created by Field(), QueryParam() or RouteParam(). Defaults to an empty array.
json()
Collect the registered body fields as a name/value map for the JSON request body.
public
json() : array<string|int, mixed>
Return values
array<string|int, mixed> —A map of field name to current value for every field-type entry.
query()
Collect the registered query parameters as a name/value map for the query string.
public
query() : array<string|int, mixed>
Return values
array<string|int, mixed> —A map of parameter name to current value for every query_param-type entry.
QueryParam()
Define a query-string parameter descriptor.
public
static QueryParam(string $name, string $vType[, bool $required = false ][, mixed $default = null ][, string $desc = "" ]) : array<string|int, mixed>
Parameters
- $name : string
-
The parameter name as sent in the query string.
- $vType : string
-
The value type (e.g.
string,integer,boolean). - $required : bool = false
-
Whether the parameter must be set before the request is sent. Defaults to false.
- $default : mixed = null
-
The default value for the parameter. Defaults to null.
- $desc : string = ""
-
A human-readable description of the parameter. Defaults to an empty string.
Return values
array<string|int, mixed> —The query parameter descriptor.
route()
Collect the registered route parameters as a name/value map for URI substitution.
public
route() : array<string|int, mixed>
Return values
array<string|int, mixed> —A map of parameter name to current value for every route_param-type entry.
RouteParam()
Define a URI route parameter descriptor.
public
static RouteParam(string $name, string $vType[, bool $required = false ][, mixed $default = null ][, string $desc = "" ]) : array<string|int, mixed>
The value substitutes a {name} placeholder in the request URI when it is
resolved by ApiBase::uriHook().
Parameters
- $name : string
-
The parameter name, matching a
{name}placeholder in the URI. - $vType : string
-
The value type (e.g.
string,integer,boolean). - $required : bool = false
-
Whether the parameter must be set before the request is sent. Defaults to false.
- $default : mixed = null
-
The default value for the parameter. Defaults to null.
- $desc : string = ""
-
A human-readable description of the parameter. Defaults to an empty string.
Return values
array<string|int, mixed> —The route parameter descriptor.
validate()
Ensure every required field has been assigned a value.
public
validate() : void