Class: WP_REST_Request

Implements \ArrayAccess

Core class used to implement a REST request object.

Contains data from the request, to be passed to the callback.

Note: This implements ArrayAccess, and acts as an array of parameters when used in that manner. It does not use ArrayObject (as we cannot rely on SPL), so be aware it may have non-array behaviour in some cases.

Note: When using features provided by ArrayAccess, be aware that WordPress deliberately does not distinguish between arguments of the same name for different request methods. For instance, in a request with GET id=1 and POST id=2, $request['id'] will equal 2 (POST) not 1 (GET). For more precision between request methods, use WP_REST_Request::get_body_params(), WP_REST_Request::get_url_params(), etc.


Properties

Name Type(s) Default Value Summary
method string HTTP method.
params array Parameters passed to the request.

These typically come from the $_GET, $_POST and $_FILES superglobals when being created from the global scope.

headers array HTTP headers for the request.
body string Body data.
route string Route matched for the request.
attributes array Attributes (options) for the route that was matched.

This is the options array used when the route was registered, typically containing the callback as well as the valid methods for the route.

parsed_json boolean Used to determine if the JSON data has been parsed yet.

Allows lazy-parsing of JSON data where possible.

parsed_body boolean Used to determine if the body data has been parsed yet.

Methods

WP_REST_Request:: __construct( string $method = '', string $route = '', array $attributes = array() )

Constructor. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$method string

Optional. Request method. Default empty.

$route string

Optional. Request route. Default empty.

$attributes array

Optional. Request attributes. Default empty array.


WP_REST_Request:: add_header( string $key, string $value )

Appends a header value for the given header. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$key string

Header name.

$value string

Header value, or list of values.


WP_REST_Request:: canonicalize_header_name( string $key )

Canonicalizes the header name. Since 4.4.0.

Ensures that header names are always treated the same regardless of source. Header names are always case insensitive.

Note that we treat - (dashes) and _ (underscores) as the same character, as per header parsing rules in both Apache and nginx.

Arguments

Name Type(s) Default Value Description
$key string

Header name.

Returns

string

Canonicalized name.


WP_REST_Request:: from_url( string $url )

Retrieves a WP_REST_Request object from a full URL. Since 4.5.0.

Arguments

Name Type(s) Default Value Description
$url string

URL with protocol, domain, path and query args.

Returns

WP_REST_Request | false

WP_REST_Request object on success, false on failure.


WP_REST_Request:: get_attributes( )

Retrieves the attributes for the request. Since 4.4.0.

These are the options for the route that was matched.

Returns

array

Attributes for the request.


WP_REST_Request:: get_body( )

Retrieves the request body content. Since 4.4.0.

Returns

string

Binary data from the request body.


WP_REST_Request:: get_body_params( )

Retrieves parameters from the body. Since 4.4.0.

These are the parameters you'd typically find in $_POST.

Returns

array

Parameter map of key to value.


WP_REST_Request:: get_content_type( )

Retrieves the content-type of the request. Since 4.4.0.

Returns

array

Map containing 'value' and 'parameters' keys.


WP_REST_Request:: get_default_params( )

Retrieves the default parameters. Since 4.4.0.

These are the parameters set in the route registration.

Returns

array

Parameter map of key to value


WP_REST_Request:: get_file_params( )

Retrieves multipart file parameters from the body. Since 4.4.0.

These are the parameters you'd typically find in $_FILES.

Returns

array

Parameter map of key to value


WP_REST_Request:: get_header( string $key )

Retrieves the given header from the request. Since 4.4.0.

If the header has multiple values, they will be concatenated with a comma as per the HTTP specification. Be aware that some non-compliant headers (notably cookie headers) cannot be joined this way.

Arguments

Name Type(s) Default Value Description
$key string

Header name, will be canonicalized to lowercase.

Returns

string | null

String value if set, null otherwise.


WP_REST_Request:: get_header_as_array( string $key )

Retrieves header values from the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$key string

Header name, will be canonicalized to lowercase.

Returns

array | null

List of string values if set, null otherwise.


WP_REST_Request:: get_headers( )

Retrieves all headers from the request. Since 4.4.0.

Returns

array

Map of key to value. Key is always lowercase, as per HTTP specification.


WP_REST_Request:: get_json_params( )

Retrieves the parameters from a JSON-formatted body. Since 4.4.0.

Returns

array

Parameter map of key to value.


WP_REST_Request:: get_method( )

Retrieves the HTTP method for the request. Since 4.4.0.

Returns

string

HTTP method.


WP_REST_Request:: get_param( string $key )

Retrieves a parameter from the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$key string

Parameter name.

Returns

mixed | null

Value if set, null otherwise.


WP_REST_Request:: get_parameter_order( )

Retrieves the parameter priority order. Since 4.4.0.

Used when checking parameters in get_param().

Returns

array

List of types to check, in order of priority.


WP_REST_Request:: get_params( )

Retrieves merged parameters from the request. Since 4.4.0.

The equivalent of get_param(), but returns all parameters for the request. Handles merging all the available values into a single array.

Returns

array

Map of key to value.


WP_REST_Request:: get_query_params( )

Retrieves parameters from the query string. Since 4.4.0.

These are the parameters you'd typically find in $_GET.

Returns

array

Parameter map of key to value


WP_REST_Request:: get_route( )

Retrieves the route that matched the request. Since 4.4.0.

Returns

string

Route matching regex.


WP_REST_Request:: get_url_params( )

Retrieves parameters from the route itself. Since 4.4.0.

These are parsed from the URL using the regex.

Returns

array

Parameter map of key to value.


WP_REST_Request:: has_valid_params( )

Checks whether this request is valid according to its attributes. Since 4.4.0.

Returns

boolean | WP_Error

True if there are no parameters to validate or if all pass validation, WP_Error if required parameters are missing.


WP_REST_Request:: offsetExists( string $offset )

Checks if a parameter is set. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$offset string

Parameter name.

Returns

boolean

Whether the parameter is set.


WP_REST_Request:: offsetGet( string $offset )

Retrieves a parameter from the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$offset string

Parameter name.

Returns

mixed | null

Value if set, null otherwise.


WP_REST_Request:: offsetSet( string $offset, mixed $value )

Sets a parameter on the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$offset string

Parameter name.

$value mixed

Parameter value.


WP_REST_Request:: offsetUnset( string $offset )

Removes a parameter from the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$offset string

Parameter name.


WP_REST_Request:: parse_body_params( )

Parses the request body parameters. Since 4.4.0.

Parses out URL-encoded bodies for request methods that aren't supported natively by PHP. In PHP 5.x, only POST has these parsed automatically.


WP_REST_Request:: parse_json_params( )

Parses the JSON parameters. Since 4.4.0. Since 4.7.0.

Avoids parsing the JSON data until we need to access it.

Returns

true | WP_Error

True if the JSON data was passed or no JSON data was provided, WP_Error if invalid JSON was passed.


WP_REST_Request:: remove_header( string $key )

Removes all values for a header. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$key string

Header name.


WP_REST_Request:: sanitize_params( )

Sanitizes (where possible) the params on the request. Since 4.4.0.

This is primarily based off the sanitize_callback param on each registered argument.

Returns

true | WP_Error

True if parameters were sanitized, WP_Error if an error occurred during sanitization.


WP_REST_Request:: set_attributes( array $attributes )

Sets the attributes for the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$attributes array

Attributes for the request.


WP_REST_Request:: set_body( string $data )

Sets body content. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$data string

Binary data from the request body.


WP_REST_Request:: set_body_params( array $params )

Sets parameters from the body. Since 4.4.0.

Typically, this is set from $_POST.

Arguments

Name Type(s) Default Value Description
$params array

Parameter map of key to value.


WP_REST_Request:: set_default_params( array $params )

Sets default parameters. Since 4.4.0.

These are the parameters set in the route registration.

Arguments

Name Type(s) Default Value Description
$params array

Parameter map of key to value.


WP_REST_Request:: set_file_params( array $params )

Sets multipart file parameters from the body. Since 4.4.0.

Typically, this is set from $_FILES.

Arguments

Name Type(s) Default Value Description
$params array

Parameter map of key to value.


WP_REST_Request:: set_header( string $key, string $value )

Sets the header on request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$key string

Header name.

$value string

Header value, or list of values.


WP_REST_Request:: set_headers( array $headers, boolean $override = true )

Sets headers on the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$headers array

Map of header name to value.

$override boolean

If true, replace the request's headers. Otherwise, merge with existing.


WP_REST_Request:: set_method( string $method )

Sets HTTP method for the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$method string

HTTP method.


WP_REST_Request:: set_param( string $key, mixed $value )

Sets a parameter on the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$key string

Parameter name.

$value mixed

Parameter value.


WP_REST_Request:: set_query_params( array $params )

Sets parameters from the query string. Since 4.4.0.

Typically, this is set from $_GET.

Arguments

Name Type(s) Default Value Description
$params array

Parameter map of key to value.


WP_REST_Request:: set_route( string $route )

Sets the route that matched the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$route string

Route matching regex.


WP_REST_Request:: set_url_params( array $params )

Sets parameters from the route. Since 4.4.0.

Typically, this is set after parsing the URL.

Arguments

Name Type(s) Default Value Description
$params array

Parameter map of key to value.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.