Docs: Add much more complete and syntactically correct documentation throughout the `WP_REST_Settings_Controller` class.
Props Soean, mrahmadawais, flixos90. See #38398. git-svn-id: https://develop.svn.wordpress.org/trunk@39030 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
parent
b58bb705ce
commit
ed2321d7f1
|
@ -1,7 +1,18 @@
|
|||
<?php
|
||||
/**
|
||||
* REST API: WP_REST_Settings_Controller class
|
||||
*
|
||||
* @package WordPress
|
||||
* @subpackage REST_API
|
||||
* @since 4.7.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* Manage a WordPress site's settings.
|
||||
* Core class used to manage a site's settings via the REST API.
|
||||
*
|
||||
* @since 4.7.0
|
||||
*
|
||||
* @see WP_REST_Controller
|
||||
*/
|
||||
class WP_REST_Settings_Controller extends WP_REST_Controller {
|
||||
|
||||
|
@ -17,9 +28,15 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
}
|
||||
|
||||
/**
|
||||
* Register the routes for the objects of the controller.
|
||||
* Registers the routes for the objects of the controller.
|
||||
*
|
||||
* @since 4.7.0
|
||||
* @access public
|
||||
*
|
||||
* @see register_rest_route()
|
||||
*/
|
||||
public function register_routes() {
|
||||
|
||||
register_rest_route( $this->namespace, '/' . $this->rest_base, array(
|
||||
array(
|
||||
'methods' => WP_REST_Server::READABLE,
|
||||
|
@ -35,23 +52,30 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
),
|
||||
'schema' => array( $this, 'get_public_item_schema' ),
|
||||
) );
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a given request has access to read and manage settings.
|
||||
* Checks if a given request has access to read and manage settings.
|
||||
*
|
||||
* @param WP_REST_Request $request Full details about the request.
|
||||
* @return boolean
|
||||
* @since 4.7.0
|
||||
* @access public
|
||||
*
|
||||
* @param WP_REST_Request $request Full details about the request.
|
||||
* @return bool True if the request has read access for the item, otherwise false.
|
||||
*/
|
||||
public function get_item_permissions_check( $request ) {
|
||||
return current_user_can( 'manage_options' );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the settings.
|
||||
* Retrieves the settings.
|
||||
*
|
||||
* @since 4.7.0
|
||||
* @access public
|
||||
*
|
||||
* @param WP_REST_Request $request Full details about the request.
|
||||
* @return WP_Error|array
|
||||
* @return array|WP_Error Array on success, or WP_Error object on failure.
|
||||
*/
|
||||
public function get_item( $request ) {
|
||||
$options = $this->get_registered_options();
|
||||
|
@ -66,11 +90,11 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
*
|
||||
* @since 4.7.0
|
||||
*
|
||||
* @param mixed $result Value to use for the requested setting. Can be a scalar
|
||||
* matching the registered schema for the setting, or null to
|
||||
* follow the default `get_option` behavior.
|
||||
* @param string $name Setting name (as shown in REST API responses).
|
||||
* @param array $args Arguments passed to `register_setting()` for this setting.
|
||||
* @param mixed $result Value to use for the requested setting. Can be a scalar
|
||||
* matching the registered schema for the setting, or null to
|
||||
* follow the default get_option() behavior.
|
||||
* @param string $name Setting name (as shown in REST API responses).
|
||||
* @param array $args Arguments passed to register_setting() for this setting.
|
||||
*/
|
||||
$response[ $name ] = apply_filters( 'rest_pre_get_setting', null, $name, $args );
|
||||
|
||||
|
@ -79,8 +103,10 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
$response[ $name ] = get_option( $args['option_name'], $args['schema']['default'] );
|
||||
}
|
||||
|
||||
// Because get_option() is lossy, we have to
|
||||
// cast values to the type they are registered with.
|
||||
/*
|
||||
* Because get_option() is lossy, we have to
|
||||
* cast values to the type they are registered with.
|
||||
*/
|
||||
$response[ $name ] = $this->prepare_value( $response[ $name ], $args['schema'] );
|
||||
}
|
||||
|
||||
|
@ -88,15 +114,17 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
}
|
||||
|
||||
/**
|
||||
* Prepare a value for output based off a schema array.
|
||||
* Prepares a value for output based off a schema array.
|
||||
*
|
||||
* @param mixed $value
|
||||
* @param array $schema
|
||||
* @return mixed
|
||||
* @since 4.7.0
|
||||
* @access protected
|
||||
*
|
||||
* @param mixed $value Value to prepare.
|
||||
* @param array $schema Schema to match.
|
||||
* @return mixed The prepared value.
|
||||
*/
|
||||
protected function prepare_value( $value, $schema ) {
|
||||
// If the value is not a scalar, it's not possible to cast it to
|
||||
// anything.
|
||||
// If the value is not a scalar, it's not possible to cast it to anything.
|
||||
if ( ! is_scalar( $value ) ) {
|
||||
return null;
|
||||
}
|
||||
|
@ -114,14 +142,17 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
}
|
||||
|
||||
/**
|
||||
* Update settings for the settings object.
|
||||
* Updates settings for the settings object.
|
||||
*
|
||||
* @param WP_REST_Request $request Full detail about the request.
|
||||
* @return WP_Error|array
|
||||
* @since 4.7.0
|
||||
* @access public
|
||||
*
|
||||
* @param WP_REST_Request $request Full details about the request.
|
||||
* @return array|WP_Error Array on success, or error object on failure.
|
||||
*/
|
||||
public function update_item( $request ) {
|
||||
$options = $this->get_registered_options();
|
||||
$params = $request->get_params();
|
||||
$params = $request->get_params();
|
||||
|
||||
foreach ( $options as $name => $args ) {
|
||||
if ( ! array_key_exists( $name, $params ) ) {
|
||||
|
@ -131,35 +162,36 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
/**
|
||||
* Filters whether to preempt a setting value update.
|
||||
*
|
||||
* Allow hijacking the setting update logic and overriding the built-in behavior by
|
||||
* Allows hijacking the setting update logic and overriding the built-in behavior by
|
||||
* returning true.
|
||||
*
|
||||
* @since 4.7.0
|
||||
*
|
||||
* @param boolean $result Whether to override the default behavior for updating the
|
||||
* value of a setting.
|
||||
* @param string $name Setting name (as shown in REST API responses).
|
||||
* @param mixed $value Updated setting value.
|
||||
* @param array $args Arguments passed to `register_setting()` for this setting.
|
||||
* @param bool $result Whether to override the default behavior for updating the
|
||||
* value of a setting.
|
||||
* @param string $name Setting name (as shown in REST API responses).
|
||||
* @param mixed $value Updated setting value.
|
||||
* @param array $args Arguments passed to register_setting() for this setting.
|
||||
*/
|
||||
$updated = apply_filters( 'rest_pre_update_setting', false, $name, $request[ $name ], $args );
|
||||
|
||||
if ( $updated ) {
|
||||
continue;
|
||||
}
|
||||
|
||||
/**
|
||||
* A `null` value for an option would have the same effect as
|
||||
* deleting the option from the database, and relying on the
|
||||
* default value.
|
||||
*/
|
||||
/*
|
||||
* A null value for an option would have the same effect as
|
||||
* deleting the option from the database, and relying on the
|
||||
* default value.
|
||||
*/
|
||||
if ( is_null( $request[ $name ] ) ) {
|
||||
/**
|
||||
* A `null` value is returned in the response for any option
|
||||
/*
|
||||
* A null value is returned in the response for any option
|
||||
* that has a non-scalar value.
|
||||
*
|
||||
* To protect clients from accidentally including the `null`
|
||||
* To protect clients from accidentally including the null
|
||||
* values from a response object in a request, we do not allow
|
||||
* options with non-scalar values to be updated to `null`.
|
||||
* options with non-scalar values to be updated to null.
|
||||
* Without this added protection a client could mistakenly
|
||||
* delete all options that have non-scalar values from the
|
||||
* database.
|
||||
|
@ -180,9 +212,12 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
}
|
||||
|
||||
/**
|
||||
* Get all the registered options for the Settings API
|
||||
* Retrieves all of the registered options for the Settings API.
|
||||
*
|
||||
* @return array
|
||||
* @since 4.7.0
|
||||
* @access protected
|
||||
*
|
||||
* @return array Array of registered options.
|
||||
*/
|
||||
protected function get_registered_options() {
|
||||
$rest_options = array();
|
||||
|
@ -193,6 +228,7 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
}
|
||||
|
||||
$rest_args = array();
|
||||
|
||||
if ( is_array( $args['show_in_rest'] ) ) {
|
||||
$rest_args = $args['show_in_rest'];
|
||||
}
|
||||
|
@ -201,6 +237,7 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
'name' => ! empty( $rest_args['name'] ) ? $rest_args['name'] : $name,
|
||||
'schema' => array(),
|
||||
);
|
||||
|
||||
$rest_args = array_merge( $defaults, $rest_args );
|
||||
|
||||
$default_schema = array(
|
||||
|
@ -217,8 +254,10 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
continue;
|
||||
}
|
||||
|
||||
// Whitelist the supported types for settings, as we don't want invalid types
|
||||
// to be updated with arbitrary values that we can't do decent sanitizing for.
|
||||
/*
|
||||
* Whitelist the supported types for settings, as we don't want invalid types
|
||||
* to be updated with arbitrary values that we can't do decent sanitizing for.
|
||||
*/
|
||||
if ( ! in_array( $rest_args['schema']['type'], array( 'number', 'string', 'boolean' ), true ) ) {
|
||||
continue;
|
||||
}
|
||||
|
@ -230,9 +269,12 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
|
|||
}
|
||||
|
||||
/**
|
||||
* Get the site setting schema, conforming to JSON Schema.
|
||||
* Retrieves the site setting schema, conforming to JSON Schema.
|
||||
*
|
||||
* @return array
|
||||
* @since 4.7.0
|
||||
* @access public
|
||||
*
|
||||
* @return array Item schema data.
|
||||
*/
|
||||
public function get_item_schema() {
|
||||
$options = $this->get_registered_options();
|
||||
|
|
Loading…
Reference in New Issue