WordPress.org

Make WordPress Core

Changeset 39030


Ignore:
Timestamp:
10/30/2016 06:00:24 PM (4 years ago)
Author:
DrewAPicture
Message:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Settings_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php

    r38982 r39030  
    11<?php
    2 
    32/**
    4  * Manage a WordPress site's settings.
     3 * REST API: WP_REST_Settings_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
     9
     10/**
     11 * Core class used to manage a site's settings via the REST API.
     12 *
     13 * @since 4.7.0
     14 *
     15 * @see WP_REST_Controller
    516 */
    617class WP_REST_Settings_Controller extends WP_REST_Controller {
     
    1829
    1930    /**
    20      * Register the routes for the objects of the controller.
     31     * Registers the routes for the objects of the controller.
     32     *
     33     * @since 4.7.0
     34     * @access public
     35     *
     36     * @see register_rest_route()
    2137     */
    2238    public function register_routes() {
     39
    2340        register_rest_route( $this->namespace, '/' . $this->rest_base, array(
    2441            array(
     
    3653            'schema' => array( $this, 'get_public_item_schema' ),
    3754        ) );
    38     }
    39 
    40     /**
    41      * Check if a given request has access to read and manage settings.
    42      *
    43      * @param  WP_REST_Request $request Full details about the request.
    44      * @return boolean
     55
     56    }
     57
     58    /**
     59     * Checks if a given request has access to read and manage settings.
     60     *
     61     * @since 4.7.0
     62     * @access public
     63     *
     64     * @param WP_REST_Request $request Full details about the request.
     65     * @return bool True if the request has read access for the item, otherwise false.
    4566     */
    4667    public function get_item_permissions_check( $request ) {
     
    4970
    5071    /**
    51      * Get the settings.
     72     * Retrieves the settings.
     73     *
     74     * @since 4.7.0
     75     * @access public
    5276     *
    5377     * @param WP_REST_Request $request Full details about the request.
    54      * @return WP_Error|array
     78     * @return array|WP_Error Array on success, or WP_Error object on failure.
    5579     */
    5680    public function get_item( $request ) {
     
    6791             * @since 4.7.0
    6892             *
    69              * @param mixed  $result  Value to use for the requested setting. Can be a scalar
    70              *                        matching the registered schema for the setting, or null to
    71              *                        follow the default `get_option` behavior.
    72              * @param string $name    Setting name (as shown in REST API responses).
    73              * @param array  $args    Arguments passed to `register_setting()` for this setting.
     93             * @param mixed  $result Value to use for the requested setting. Can be a scalar
     94             *                       matching the registered schema for the setting, or null to
     95             *                       follow the default get_option() behavior.
     96             * @param string $name   Setting name (as shown in REST API responses).
     97             * @param array  $args   Arguments passed to register_setting() for this setting.
    7498             */
    7599            $response[ $name ] = apply_filters( 'rest_pre_get_setting', null, $name, $args );
     
    80104            }
    81105
    82             // Because get_option() is lossy, we have to
    83             // cast values to the type they are registered with.
     106            /*
     107             * Because get_option() is lossy, we have to
     108             * cast values to the type they are registered with.
     109             */
    84110            $response[ $name ] = $this->prepare_value( $response[ $name ], $args['schema'] );
    85111        }
     
    89115
    90116    /**
    91      * Prepare a value for output based off a schema array.
    92      *
    93      * @param  mixed $value
    94      * @param  array $schema
    95      * @return mixed
     117     * Prepares a value for output based off a schema array.
     118     *
     119     * @since 4.7.0
     120     * @access protected
     121     *
     122     * @param mixed $value  Value to prepare.
     123     * @param array $schema Schema to match.
     124     * @return mixed The prepared value.
    96125     */
    97126    protected function prepare_value( $value, $schema ) {
    98         // If the value is not a scalar, it's not possible to cast it to
    99         // anything.
     127        // If the value is not a scalar, it's not possible to cast it to anything.
    100128        if ( ! is_scalar( $value ) ) {
    101129            return null;
     
    115143
    116144    /**
    117      * Update settings for the settings object.
    118      *
    119      * @param  WP_REST_Request $request Full detail about the request.
    120      * @return WP_Error|array
     145     * Updates settings for the settings object.
     146     *
     147     * @since 4.7.0
     148     * @access public
     149     *
     150     * @param WP_REST_Request $request Full details about the request.
     151     * @return array|WP_Error Array on success, or error object on failure.
    121152     */
    122153    public function update_item( $request ) {
    123154        $options = $this->get_registered_options();
    124         $params = $request->get_params();
     155        $params  = $request->get_params();
    125156
    126157        foreach ( $options as $name => $args ) {
     
    132163             * Filters whether to preempt a setting value update.
    133164             *
    134              * Allow hijacking the setting update logic and overriding the built-in behavior by
     165             * Allows hijacking the setting update logic and overriding the built-in behavior by
    135166             * returning true.
    136167             *
    137168             * @since 4.7.0
    138169             *
    139              * @param boolean $result Whether to override the default behavior for updating the
    140              *                        value of a setting.
    141              * @param string  $name   Setting name (as shown in REST API responses).
    142              * @param mixed   $value  Updated setting value.
    143              * @param array   $args   Arguments passed to `register_setting()` for this setting.
     170             * @param bool  $result Whether to override the default behavior for updating the
     171             *                       value of a setting.
     172             * @param string $name   Setting name (as shown in REST API responses).
     173             * @param mixed  $value  Updated setting value.
     174             * @param array  $args   Arguments passed to register_setting() for this setting.
    144175             */
    145176            $updated = apply_filters( 'rest_pre_update_setting', false, $name, $request[ $name ], $args );
     177
    146178            if ( $updated ) {
    147179                continue;
    148180            }
    149181
    150             /**
    151             * A `null` value for an option would have the same effect as
    152             * deleting the option from the database, and relying on the
    153             * default value.
    154             */
     182            /*
     183             * A null value for an option would have the same effect as
     184             * deleting the option from the database, and relying on the
     185             * default value.
     186             */
    155187            if ( is_null( $request[ $name ] ) ) {
    156                 /**
    157                  * A `null` value is returned in the response for any option
     188                /*
     189                 * A null value is returned in the response for any option
    158190                 * that has a non-scalar value.
    159191                 *
    160                  * To protect clients from accidentally including the `null`
     192                 * To protect clients from accidentally including the null
    161193                 * values from a response object in a request, we do not allow
    162                  * options with non-scalar values to be updated to `null`.
     194                 * options with non-scalar values to be updated to null.
    163195                 * Without this added protection a client could mistakenly
    164196                 * delete all options that have non-scalar values from the
     
    181213
    182214    /**
    183      * Get all the registered options for the Settings API
    184      *
    185      * @return array
     215     * Retrieves all of the registered options for the Settings API.
     216     *
     217     * @since 4.7.0
     218     * @access protected
     219     *
     220     * @return array Array of registered options.
    186221     */
    187222    protected function get_registered_options() {
     
    194229
    195230            $rest_args = array();
     231
    196232            if ( is_array( $args['show_in_rest'] ) ) {
    197233                $rest_args = $args['show_in_rest'];
     
    202238                'schema' => array(),
    203239            );
     240
    204241            $rest_args = array_merge( $defaults, $rest_args );
    205242
     
    218255            }
    219256
    220             // Whitelist the supported types for settings, as we don't want invalid types
    221             // to be updated with arbitrary values that we can't do decent sanitizing for.
     257            /*
     258             * Whitelist the supported types for settings, as we don't want invalid types
     259             * to be updated with arbitrary values that we can't do decent sanitizing for.
     260             */
    222261            if ( ! in_array( $rest_args['schema']['type'], array( 'number', 'string', 'boolean' ), true ) ) {
    223262                continue;
     
    231270
    232271    /**
    233      * Get the site setting schema, conforming to JSON Schema.
    234      *
    235      * @return array
     272     * Retrieves the site setting schema, conforming to JSON Schema.
     273     *
     274     * @since 4.7.0
     275     * @access public
     276     *
     277     * @return array Item schema data.
    236278     */
    237279    public function get_item_schema() {
Note: See TracChangeset for help on using the changeset viewer.