Class: WP_REST_Settings_Controller

Extends WP_REST_Controller

Core class used to manage a site's settings via the REST API.

Properties


Properties

Name Type(s) Default Value Summary
namespace string Inherited ⋅ The namespace of this controller's route.
rest_base string Inherited ⋅ The base of this controller's route.

Methods

WP_REST_Settings_Controller:: __construct( )

Constructor. Since 4.7.0.


WP_REST_Settings_Controller:: add_additional_fields_schema( array $schema )

Adds the schema from additional fields to a schema array. Since 4.7.0.

The type of object is inferred from the passed schema.

Arguments

Name Type(s) Default Value Description
$schema array

Schema array.

Returns

array

Modified Schema array.


WP_REST_Settings_Controller:: add_additional_fields_to_object( array $object, WP_REST_Request $request )

Adds the values from additional fields to a data object. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$object array

Data object.

$request WP_REST_Request

Full details about the request.

Returns

array

Modified data object with additional fields.


WP_REST_Settings_Controller:: create_item( WP_REST_Request $request )

Creates one item from the collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Settings_Controller:: create_item_permissions_check( WP_REST_Request $request )

Checks if a given request has access to create items. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has access to create items, WP_Error object otherwise.


WP_REST_Settings_Controller:: delete_item( WP_REST_Request $request )

Deletes one item from the collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Settings_Controller:: delete_item_permissions_check( WP_REST_Request $request )

Checks if a given request has access to delete a specific item. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has access to delete the item, WP_Error object otherwise.


WP_REST_Settings_Controller:: filter_response_by_context( array $data, string $context )

Filters a response based on the context defined in the schema. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$data array

Response data to fiter.

$context string

Context defined in the schema.

Returns

array

Filtered response.


WP_REST_Settings_Controller:: get_additional_fields( string $object_type = null )

Retrieves all of the registered additional fields for a given object-type. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$object_type string

Optional. The object type.

Returns

array

Registered additional fields (if any), empty array if none or if the object type could not be inferred.


WP_REST_Settings_Controller:: get_collection_params( )

Retrieves the query params for the collections. Since 4.7.0.

Returns

array

Query parameters for the collection.


WP_REST_Settings_Controller:: get_context_param( array $args = array() )

Retrieves the magical context param. Since 4.7.0.

Ensures consistent descriptions between endpoints, and populates enum from schema.

Arguments

Name Type(s) Default Value Description
$args array

Optional. Additional arguments for context parameter. Default empty array.

Returns

array

Context parameter details.


WP_REST_Settings_Controller:: get_endpoint_args_for_item_schema( string $method = \WP_REST_Server::CREATABLE )

Retrieves an array of endpoint arguments from the item schema for the controller. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$method string

Optional. HTTP method of the request. The arguments for CREATABLE requests are checked for required values and may fall-back to a given default, this is not done on EDITABLE requests. Default WP_REST_Server::CREATABLE.

Returns

array

Endpoint arguments.


WP_REST_Settings_Controller:: get_fields_for_response( WP_REST_Request $request )

Gets an array of fields to be included on the response. Since 4.9.6.

Included fields are based on item schema and _fields= request argument.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full details about the request.

Returns

array

Fields to be included in the response.


WP_REST_Settings_Controller:: get_item( WP_REST_Request $request )

Retrieves one item from the collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Settings_Controller:: get_item_permissions_check( WP_REST_Request $request )

Checks if a given request has access to get a specific item. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has read access for the item, WP_Error object otherwise.


WP_REST_Settings_Controller:: get_item_schema( )

Retrieves the item's schema, conforming to JSON Schema. Since 4.7.0.

Returns

array

Item schema data.


WP_REST_Settings_Controller:: get_items( WP_REST_Request $request )

Retrieves a collection of items. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Settings_Controller:: get_items_permissions_check( WP_REST_Request $request )

Checks if a given request has access to get items. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has read access, WP_Error object otherwise.


WP_REST_Settings_Controller:: get_object_type( )

Retrieves the object type this controller is responsible for managing. Since 4.7.0.

Returns

string

Object type for the controller.


WP_REST_Settings_Controller:: get_public_item_schema( )

Retrieves the item's schema for display / public consumption purposes. Since 4.7.0.

Returns

array

Public item schema data.


WP_REST_Settings_Controller:: get_registered_options( )

Retrieves all of the registered options for the Settings API. Since 4.7.0.

Returns

array

Array of registered options.


WP_REST_Settings_Controller:: prepare_item_for_database( WP_REST_Request $request )

Prepares one item for create or update operation. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Request object.

Returns

WP_Error | object

The prepared item, or WP_Error object on failure.


WP_REST_Settings_Controller:: prepare_item_for_response( mixed $item, WP_REST_Request $request )

Prepares the item for the REST response. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$item mixed

WordPress representation of the item.

$request WP_REST_Request

Request object.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Settings_Controller:: prepare_response_for_collection( WP_REST_Response $response )

Prepares a response for insertion into a collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$response WP_REST_Response

Response object.

Returns

array | mixed

Response data, ready for insertion into collection data.


WP_REST_Settings_Controller:: prepare_value( mixed $value, array $schema )

Prepares a value for output based off a schema array. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Value to prepare.

$schema array

Schema to match.

Returns

mixed

The prepared value.


WP_REST_Settings_Controller:: register_routes( )

Registers the routes for the objects of the controller. Since 4.7.0.


WP_REST_Settings_Controller:: sanitize_callback( mixed $value, WP_REST_Request $request, string $param )

Custom sanitize callback used for all options to allow the use of 'null'. Since 4.7.0.

By default, the schema of settings will throw an error if a value is set to null as it's not a valid value for something like "type => string". We provide a wrapper sanitizer to whitelist the use of null.

Arguments

Name Type(s) Default Value Description
$value mixed

The value for the setting.

$request WP_REST_Request

The request object.

$param string

The parameter name.

Returns

mixed | WP_Error


WP_REST_Settings_Controller:: set_additional_properties_to_false( array $schema )

Recursively add additionalProperties = false to all objects in a schema. Since 4.9.0.

This is need to restrict properties of objects in settings values to only registered items, as the REST API will allow additional properties by default.

Arguments

Name Type(s) Default Value Description
$schema array

The schema array.

Returns

array


WP_REST_Settings_Controller:: update_additional_fields_for_object( array $object, WP_REST_Request $request )

Updates the values of additional fields added to a data object. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$object array

Data Object.

$request WP_REST_Request

Full details about the request.

Returns

boolean | WP_Error

True on success, WP_Error object if a field cannot be updated.


WP_REST_Settings_Controller:: update_item( WP_REST_Request $request )

Updates one item from the collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Settings_Controller:: update_item_permissions_check( WP_REST_Request $request )

Checks if a given request has access to update a specific item. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has access to update the item, WP_Error object otherwise.


WordPress Developer Newsletter

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