• Home
  • WP_REST_Server

PHP Class WP_REST_Server, wordpress

Since: 4.4.0
Show file Open project: johnpbloch/wordpress Class Usage Examples

Protected Properties

Property Type Description
$endpoints array Endpoints registered to the server.
$namespaces array Namespaces registered to the server.
$route_options array Options defined for the routes.

Public Methods

Method Description
__construct ( ) Instantiates the REST server.
check_authentication ( ) : WP_Error | null Checks the authentication headers if supplied.
dispatch ( WP_REST_Request $request ) : WP_REST_Response Matches the request to a callback and call it.
envelope_response ( WP_REST_Response $response, boolean $embed ) : WP_REST_Response Wraps the response in an envelope.
get_compact_response_links ( WP_REST_Response $response ) : array Retrieves the CURIEs (compact URIs) used for relations.
get_data_for_route ( string $route, array $callbacks, string $context = 'view' ) : array | null Retrieves publicly-visible data for the route.
get_data_for_routes ( array $routes, string $context = 'view' ) : array Retrieves the publicly-visible data for routes.
get_headers ( array $server ) : array Extracts headers from a PHP-style $_SERVER array.
get_index ( array $request ) : array Retrieves the site index.
get_namespace_index ( WP_REST_Request $request ) : WP_REST_Response | WP_Error Retrieves the index for a namespace.
get_namespaces ( ) : array Retrieves namespaces registered on the server.
get_raw_data ( ) : string Retrieves the raw request entity (body).
get_response_links ( WP_REST_Response $response ) : array Retrieves links from a response.
get_route_options ( string $route ) : array | null Retrieves specified options for a route.
get_routes ( ) : array Retrieves the route map.
register_route ( string $namespace, string $route, array $route_args, boolean $override = false ) Registers a route to the server.
response_to_data ( WP_REST_Response $response, boolean $embed ) : array Converts a response to data to send.
send_header ( string $key, string $value ) Sends an HTTP header.
send_headers ( array $headers ) Sends multiple HTTP headers.
serve_request ( string $path = null ) : false | null Handles serving an API request.

Protected Methods

Method Description
embed_links ( array $data ) : array Embeds the links from the data into the request.
error_to_response ( WP_Error $error ) : WP_REST_Response Converts an error to a response object.
get_json_last_error ( ) : boolean | string Returns if an error occurred during most recent JSON encode/decode.
json_error ( string $code, string $message, integer $status = null ) : string Retrieves an appropriate error representation in JSON.
set_status ( integer $code ) Sends an HTTP status code.

Method Details

__construct() public method

Instantiates the REST server.
Since: 4.4.0
public __construct ( )

check_authentication() public method

Checks the authentication headers if supplied.
Since: 4.4.0
public check_authentication ( ) : WP_Error | null
return WP_Error | null WP_Error indicates unsuccessful login, null indicates successful or no authentication provided

dispatch() public method

Matches the request to a callback and call it.
Since: 4.4.0
public dispatch ( WP_REST_Request $request ) : WP_REST_Response
$request WP_REST_Request Request to attempt dispatching.
return WP_REST_Response Response returned by the callback.

envelope_response() public method

The enveloping technique is used to work around browser/client compatibility issues. Essentially, it converts the full HTTP response to data instead.
Since: 4.4.0
public envelope_response ( WP_REST_Response $response, boolean $embed ) : WP_REST_Response
$response WP_REST_Response Response object.
$embed boolean Whether links should be embedded.
return WP_REST_Response New response with wrapped data

error_to_response() protected method

This iterates over all error codes and messages to change it into a flat array. This enables simpler client behaviour, as it is represented as a list in JSON rather than an object/map.
Since: 4.4.0
protected error_to_response ( WP_Error $error ) : WP_REST_Response
$error WP_Error WP_Error instance.
return WP_REST_Response List of associative arrays with code and message keys.

get_data_for_route() public method

Retrieves publicly-visible data for the route.
Since: 4.4.0
public get_data_for_route ( string $route, array $callbacks, string $context = 'view' ) : array | null
$route string Route to get data for.
$callbacks array Callbacks to convert to data.
$context string Optional. Context for the data. Accepts 'view' or 'help'. Default 'view'.
return array | null Data for the route, or null if no publicly-visible data.

get_data_for_routes() public method

Retrieves the publicly-visible data for routes.
Since: 4.4.0
public get_data_for_routes ( array $routes, string $context = 'view' ) : array
$routes array Routes to get data for.
$context string Optional. Context for data. Accepts 'view' or 'help'. Default 'view'.
return array Route data to expose in indexes.

get_headers() public method

Extracts headers from a PHP-style $_SERVER array.
Since: 4.4.0
public get_headers ( array $server ) : array
$server array Associative array similar to `$_SERVER`.
return array Headers extracted from the input.

get_index() public method

This endpoint describes the capabilities of the site.
Since: 4.4.0
public get_index ( array $request ) : array
$request array { Request. @type string $context Context. }
return array Index entity

get_json_last_error() protected method

Strings to be translated will be in format like "Encoding error: Maximum stack depth exceeded".
Since: 4.4.0
protected get_json_last_error ( ) : boolean | string
return boolean | string Boolean false or string error message.

get_namespace_index() public method

Retrieves the index for a namespace.
Since: 4.4.0
public get_namespace_index ( WP_REST_Request $request ) : WP_REST_Response | WP_Error
$request WP_REST_Request REST request instance.
return WP_REST_Response | WP_Error WP_REST_Response instance if the index was found, WP_Error if the namespace isn't set.

get_namespaces() public method

Retrieves namespaces registered on the server.
Since: 4.4.0
public get_namespaces ( ) : array
return array List of registered namespaces.

get_raw_data() public static method

Retrieves the raw request entity (body).
Since: 4.4.0
public static get_raw_data ( ) : string
return string Raw request data.

get_route_options() public method

Retrieves specified options for a route.
Since: 4.4.0
public get_route_options ( string $route ) : array | null
$route string Route pattern to fetch options for.
return array | null Data as an associative array if found, or null if not found.

get_routes() public method

The route map is an associative array with path regexes as the keys. The value is an indexed array with the callback function/method as the first item, and a bitmask of HTTP methods as the second item (see the class constants). Each route can be mapped to more than one callback by using an array of the indexed arrays. This allows mapping e.g. GET requests to one callback and POST requests to another. Note that the path regexes (array keys) must have @ escaped, as this is used as the delimiter with preg_match()
Since: 4.4.0
public get_routes ( ) : array
return array `'/path/regex' => array( $callback, $bitmask )` or `'/path/regex' => array( array( $callback, $bitmask ), ...)`.

json_error() protected method

Note: This should only be used in WP_REST_Server::serve_request(), as it cannot handle WP_Error internally. All callbacks and other internal methods should instead return a WP_Error with the data set to an array that includes a 'status' key, with the value being the HTTP status to send.
Since: 4.4.0
protected json_error ( string $code, string $message, integer $status = null ) : string
$code string WP_Error-style code.
$message string Human-readable message.
$status integer Optional. HTTP status code to send. Default null.
return string JSON representation of the error

register_route() public method

Registers a route to the server.
Since: 4.4.0
public register_route ( string $namespace, string $route, array $route_args, boolean $override = false )
$namespace string Namespace.
$route string The REST route.
$route_args array Route arguments.
$override boolean Optional. Whether the route should be overridden if it already exists. Default false.

response_to_data() public method

Converts a response to data to send.
Since: 4.4.0
public response_to_data ( WP_REST_Response $response, boolean $embed ) : array
$response WP_REST_Response Response object.
$embed boolean Whether links should be embedded.
return array { Data with sub-requests embedded. @type array [$_links] Links. @type array [$_embedded] Embeddeds. }

send_header() public method

Sends an HTTP header.
Since: 4.4.0
public send_header ( string $key, string $value )
$key string Header key.
$value string Header value.

send_headers() public method

Sends multiple HTTP headers.
Since: 4.4.0
public send_headers ( array $headers )
$headers array Map of header name to header value.

serve_request() public method

Matches the current server URI to a route and runs the first matching callback then outputs a JSON representation of the returned value.
See also: WP_REST_Server::dispatch()
Since: 4.4.0
public serve_request ( string $path = null ) : false | null
$path string Optional. The request route. If not set, `$_SERVER['PATH_INFO']` will be used. Default null.
return false | null Null if not served and a HEAD request, false otherwise.

set_status() protected method

Sends an HTTP status code.
Since: 4.4.0
protected set_status ( integer $code )
$code integer HTTP status.

Property Details

$endpoints protected property

Endpoints registered to the server.
Since: 4.4.0
protected array $endpoints
return array

$namespaces protected property

Namespaces registered to the server.
Since: 4.4.0
protected array $namespaces
return array

$route_options protected property

Options defined for the routes.
Since: 4.4.0
protected array $route_options
return array