WordPress.org
Get WordPress

Make WordPress Core

Changeset 39021


Ignore:
Timestamp:
10/30/2016 04:19:22 PM (8 years ago)
Author:
DrewAPicture
Message:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_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-controller.php

    r38832 r39021  
    11<?php
    2 
    3 
     2/**
     3 * REST API: WP_REST_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
     9
     10/**
     11 * Core base controller for managing and interacting with REST API items.
     12 *
     13 * @since 4.7.0
     14 */
    415abstract class WP_REST_Controller {
    516
    … …  
    718     * The namespace of this controller's route.
    819     *
     20     * @since 4.7.0
     21     * @access protected
    922     * @var string
    1023     */
    … …  
    1427     * The base of this controller's route.
    1528     *
     29     * @since 4.7.0
     30     * @access protected
    1631     * @var string
    1732     */
    … …  
    1934
    2035    /**
    21      * Register the routes for the objects of the controller.
     36     * Registers the routes for the objects of the controller.
     37     *
     38     * @since 4.7.0
     39     * @access public
    2240     */
    2341    public function register_routes() {
    24         _doing_it_wrong( 'WP_REST_Controller::register_routes', __( 'The register_routes() method must be overridden' ), 'WPAPI-2.0' );
    25     }
    26 
    27     /**
    28      * Check if a given request has access to get items.
    29      *
    30      * @param WP_REST_Request $request Full data about the request.
    31      * @return WP_Error|boolean
     42        _doing_it_wrong( 'WP_REST_Controller::register_routes', __( 'The register_routes() method must be overridden' ), '4.7' );
     43    }
     44
     45    /**
     46     * Checks if a given request has access to get items.
     47     *
     48     * @since 4.7.0
     49     * @access public
     50     *
     51     * @param WP_REST_Request $request Full data about the request.
     52     * @return WP_Error|bool True if the request has read access, WP_Error object otherwise.
    3253     */
    3354    public function get_items_permissions_check( $request ) {
    … …  
    3657
    3758    /**
    38      * Get a collection of items.
    39      *
    40      * @param WP_REST_Request $request Full data about the request.
    41      * @return WP_Error|WP_REST_Response
     59     * Retrieves a collection of items.
     60     *
     61     * @since 4.7.0
     62     * @access public
     63     *
     64     * @param WP_REST_Request $request Full data about the request.
     65     * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    4266     */
    4367    public function get_items( $request ) {
    … …  
    4670
    4771    /**
    48      * Check if a given request has access to get a specific item.
    49      *
    50      * @param WP_REST_Request $request Full data about the request.
    51      * @return WP_Error|boolean
     72     * Checks if a given request has access to get a specific item.
     73     *
     74     * @since 4.7.0
     75     * @access public
     76     *
     77     * @param WP_REST_Request $request Full data about the request.
     78     * @return WP_Error|bool True if the request has read access for the item, WP_Error object otherwise.
    5279     */
    5380    public function get_item_permissions_check( $request ) {
    … …  
    5683
    5784    /**
    58      * Get one item from the collection.
    59      *
    60      * @param WP_REST_Request $request Full data about the request.
    61      * @return WP_Error|WP_REST_Response
     85     * Retrieves one item from the collection.
     86     *
     87     * @since 4.7.0
     88     * @access public
     89     *
     90     * @param WP_REST_Request $request Full data about the request.
     91     * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    6292     */
    6393    public function get_item( $request ) {
    … …  
    6696
    6797    /**
    68      * Check if a given request has access to create items.
    69      *
    70      * @param WP_REST_Request $request Full data about the request.
    71      * @return WP_Error|boolean
     98     * Checks if a given request has access to create items.
     99     *
     100     * @since 4.7.0
     101     * @access public
     102     *
     103     * @param WP_REST_Request $request Full data about the request.
     104     * @return WP_Error|bool True if the request has access to create items, WP_Error object otherwise.
    72105     */
    73106    public function create_item_permissions_check( $request ) {
    … …  
    76109
    77110    /**
    78      * Create one item from the collection.
    79      *
    80      * @param WP_REST_Request $request Full data about the request.
    81      * @return WP_Error|WP_REST_Response
     111     * Creates one item from the collection.
     112     *
     113     * @since 4.7.0
     114     * @access public
     115     *
     116     * @param WP_REST_Request $request Full data about the request.
     117     * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    82118     */
    83119    public function create_item( $request ) {
    … …  
    86122
    87123    /**
    88      * Check if a given request has access to update a specific item.
    89      *
    90      * @param WP_REST_Request $request Full data about the request.
    91      * @return WP_Error|boolean
     124     * Checks if a given request has access to update a specific item.
     125     *
     126     * @since 4.7.0
     127     * @access public
     128     *
     129     * @param WP_REST_Request $request Full data about the request.
     130     * @return WP_Error|bool True if the request has access to update the item, WP_Error object otherwise.
    92131     */
    93132    public function update_item_permissions_check( $request ) {
    … …  
    96135
    97136    /**
    98      * Update one item from the collection.
    99      *
    100      * @param WP_REST_Request $request Full data about the request.
    101      * @return WP_Error|WP_REST_Response
     137     * Updates one item from the collection.
     138     *
     139     * @since 4.7.0
     140     * @access public
     141     *
     142     * @param WP_REST_Request $request Full data about the request.
     143     * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    102144     */
    103145    public function update_item( $request ) {
    … …  
    106148
    107149    /**
    108      * Check if a given request has access to delete a specific item.
    109      *
    110      * @param WP_REST_Request $request Full data about the request.
    111      * @return WP_Error|boolean
     150     * Checks if a given request has access to delete a specific item.
     151     *
     152     * @since 4.7.0
     153     * @access public
     154     *
     155     * @param WP_REST_Request $request Full data about the request.
     156     * @return WP_Error|bool True if the request has access to delete the item, WP_Error object otherwise.
    112157     */
    113158    public function delete_item_permissions_check( $request ) {
    … …  
    116161
    117162    /**
    118      * Delete one item from the collection.
    119      *
    120      * @param WP_REST_Request $request Full data about the request.
    121      * @return WP_Error|WP_REST_Response
     163     * Deletes one item from the collection.
     164     *
     165     * @since 4.7.0
     166     * @access public
     167     *
     168     * @param WP_REST_Request $request Full data about the request.
     169     * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    122170     */
    123171    public function delete_item( $request ) {
    … …  
    126174
    127175    /**
    128      * Prepare the item for create or update operation.
     176     * Prepares one item for create or update operation.
     177     *
     178     * @since 4.7.0
     179     * @access public
    129180     *
    130181     * @param WP_REST_Request $request Request object.
    131      * @return WP_Error|object $prepared_item
     182     * @return WP_Error|object The prepared item, or WP_Error object on failure.
    132183     */
    133184    protected function prepare_item_for_database( $request ) {
    … …  
    136187
    137188    /**
    138      * Prepare the item for the REST response.
    139      *
    140      * @param mixed $item WordPress representation of the item.
     189     * Prepares the item for the REST response.
     190     *
     191     * @since 4.7.0
     192     * @access public
     193     *
     194     * @param mixed           $item    WordPress representation of the item.
    141195     * @param WP_REST_Request $request Request object.
    142      * @return WP_Error|WP_REST_Response $response
     196     * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    143197     */
    144198    public function prepare_item_for_response( $item, $request ) {
    … …  
    147201
    148202    /**
    149      * Prepare a response for inserting into a collection.
     203     * Prepares a response for insertion into a collection.
     204     *
     205     * @since 4.7.0
     206     * @access public
    150207     *
    151208     * @param WP_REST_Response $response Response object.
    152      * @return array Response data, ready for insertion into collection data.
     209     * @return array|mixed Response data, ready for insertion into collection data.
    153210     */
    154211    public function prepare_response_for_collection( $response ) {
    … …  
    157214        }
    158215
    159         $data = (array) $response->get_data();
     216        $data   = (array) $response->get_data();
    160217        $server = rest_get_server();
    161218
    … …  
    174231
    175232    /**
    176      * Filter a response based on the context defined in the schema.
    177      *
    178      * @param array $data
    179      * @param string $context
    180      * @return array
     233     * Filters a response based on the context defined in the schema.
     234     *
     235     * @since 4.7.0
     236     * @access public
     237     *
     238     * @param array  $data    Response data to fiter.
     239     * @param string $context Context defined in the schema.
     240     * @return array Filtered response.
    181241     */
    182242    public function filter_response_by_context( $data, $context ) {
    183243
    184244        $schema = $this->get_item_schema();
     245
    185246        foreach ( $data as $key => $value ) {
    186247            if ( empty( $schema['properties'][ $key ] ) || empty( $schema['properties'][ $key ]['context'] ) ) {
    … …  
    198259                        continue;
    199260                    }
     261
    200262                    if ( ! in_array( $context, $details['context'], true ) ) {
    201263                        if ( isset( $data[ $key ][ $attribute ] ) ) {
    … …  
    211273
    212274    /**
    213      * Get the item's schema, conforming to JSON Schema.
    214      *
    215      * @return array
     275     * Retrieves the item's schema, conforming to JSON Schema.
     276     *
     277     * @since 4.7.0
     278     * @access public
     279     *
     280     * @return array Item schema data.
    216281     */
    217282    public function get_item_schema() {
    … …  
    220285
    221286    /**
    222      * Get the item's schema for display / public consumption purposes.
    223      *
    224      * @return array
     287     * Retrieves the item's schema for display / public consumption purposes.
     288     *
     289     * @since 4.7.0
     290     * @access public
     291     *
     292     * @return array Public item schema data.
    225293     */
    226294    public function get_public_item_schema() {
    … …  
    236304
    237305    /**
    238      * Get the query params for collections.
    239      *
    240      * @return array
     306     * Retrieves the query params for the collections.
     307     *
     308     * @since 4.7.0
     309     * @access public
     310     *
     311     * @return array Query parameters for the collection.
    241312     */
    242313    public function get_collection_params() {
    … …  
    270341
    271342    /**
    272      * Get the magical context param.
    273      *
    274      * Ensures consistent description between endpoints, and populates enum from schema.
    275      *
    276      * @param array     $args
    277      * @return array
     343     * Retrieves the magical context param.
     344     *
     345     * Ensures consistent descriptions between endpoints, and populates enum from schema.
     346     *
     347     * @since 4.7.0
     348     * @access public
     349     *
     350     * @param array $args Optional. Additional arguments for context parameter. Default empty array.
     351     * @return array Context parameter details.
    278352     */
    279353    public function get_context_param( $args = array() ) {
    … …  
    284358            'validate_callback'  => 'rest_validate_request_arg',
    285359        );
     360
    286361        $schema = $this->get_item_schema();
     362
    287363        if ( empty( $schema['properties'] ) ) {
    288364            return array_merge( $param_details, $args );
    289365        }
     366
    290367        $contexts = array();
     368
    291369        foreach ( $schema['properties'] as $attributes ) {
    292370            if ( ! empty( $attributes['context'] ) ) {
    … …  
    294372            }
    295373        }
     374
    296375        if ( ! empty( $contexts ) ) {
    297376            $param_details['enum'] = array_unique( $contexts );
    298377            rsort( $param_details['enum'] );
    299378        }
     379
    300380        return array_merge( $param_details, $args );
    301381    }
    302382
    303383    /**
    304      * Add the values from additional fields to a data object.
    305      *
    306      * @param array  $object
    307      * @param WP_REST_Request $request
    308      * @return array modified object with additional fields.
     384     * Adds the values from additional fields to a data object.
     385     *
     386     * @since 4.7.0
     387     * @access protected
     388     *
     389     * @param array           $object  Data object.
     390     * @param WP_REST_Request $request Full details about the request.
     391     * @return array Modified data object with additional fields.
    309392     */
    310393    protected function add_additional_fields_to_object( $object, $request ) {
    … …  
    325408
    326409    /**
    327      * Update the values of additional fields added to a data object.
    328      *
    329      * @param array  $object
    330      * @param WP_REST_Request $request
     410     * Updates the values of additional fields added to a data object.
     411     *
     412     * @since 4.7.0
     413     * @access protected
     414     *
     415     * @param array           $object  Data Object.
     416     * @param WP_REST_Request $request Full details about the request.
    331417     * @return bool|WP_Error True on success, WP_Error object if a field cannot be updated.
    332418     */
    … …  
    345431
    346432            $result = call_user_func( $field_options['update_callback'], $request[ $field_name ], $object, $field_name, $request, $this->get_object_type() );
     433
    347434            if ( is_wp_error( $result ) ) {
    348435                return $result;
    … …  
    354441
    355442    /**
    356      * Add the schema from additional fields to an schema array.
     443     * Adds the schema from additional fields to a schema array.
    357444     *
    358445     * The type of object is inferred from the passed schema.
     446     *
     447     * @since 4.7.0
     448     * @access protected
    359449     *
    360450     * @param array $schema Schema array.
    … …  
    366456        }
    367457
    368         /**
    369          * Can't use $this->get_object_type otherwise we cause an inf loop.
    370          */
     458        // Can't use $this->get_object_type otherwise we cause an inf loop.
    371459        $object_type = $schema['title'];
    372460
    … …  
    385473
    386474    /**
    387      * Get all the registered additional fields for a given object-type.
    388      *
    389      * @param  string $object_type
    390      * @return array
     475     * Retrieves all of the registered additional fields for a given object-type.
     476     *
     477     * @since 4.7.0
     478     * @access protected
     479     *
     480     * @param  string $object_type Optional. The object type.
     481     * @return array Registered additional fields (if any), empty array if none or if the object type could
     482     *               not be inferred.
    391483     */
    392484    protected function get_additional_fields( $object_type = null ) {
    … …  
    410502
    411503    /**
    412      * Get the object type this controller is responsible for managing.
    413      *
    414      * @return string
     504     * Retrieves the object type this controller is responsible for managing.
     505     *
     506     * @since 4.7.0
     507     * @access protected
     508     *
     509     * @return string Object type for the controller.
    415510     */
    416511    protected function get_object_type() {
    … …  
    425520
    426521    /**
    427      * Get an array of endpoint arguments from the item schema for the controller.
    428      *
    429      * @param string $method HTTP method of the request. The arguments
    430      *                       for `CREATABLE` requests are checked for required
    431      *                       values and may fall-back to a given default, this
    432      *                       is not done on `EDITABLE` requests. Default is
    433      *                       WP_REST_Server::CREATABLE.
    434      * @return array $endpoint_args
     522     * Retrieves an array of endpoint arguments from the item schema for the controller.
     523     *
     524     * @since 4.7.0
     525     * @access public
     526     *
     527     * @param string $method Optional. HTTP method of the request. The arguments for `CREATABLE` requests are
     528     *                       checked for required values and may fall-back to a given default, this is not done
     529     *                       on `EDITABLE` requests. Default WP_REST_Server::CREATABLE.
     530     * @return array Endpoint arguments.
    435531     */
    436532    public function get_endpoint_args_for_item_schema( $method = WP_REST_Server::CREATABLE ) {
    437533
    438         $schema                = $this->get_item_schema();
    439         $schema_properties     = ! empty( $schema['properties'] ) ? $schema['properties'] : array();
    440         $endpoint_args = array();
     534        $schema            = $this->get_item_schema();
     535        $schema_properties = ! empty( $schema['properties'] ) ? $schema['properties'] : array();
     536        $endpoint_args     = array();
    441537
    442538        foreach ( $schema_properties as $field_id => $params ) {
    … …  
    493589     * post that is used in the REST API.
    494590     *
     591     * @since 4.7.0
     592     * @access public
     593     *
    495594     * @see get_post()
    496595     * @global WP_Query $wp_query
    497596     *
    498      * @param int|WP_Post $post Post ID or post object. Defaults to global $post.
    499      * @return WP_Post|null A `WP_Post` object when successful.
     597     * @param int|WP_Post $post Post ID or object. Defaults to global `$post` object.
     598     * @return WP_Post|null A WP_Post object when successful, otherwise null.
    500599     */
    501600    public function get_post( $post ) {
    … …  
    503602
    504603        /**
    505          * Filter the post.
     604         * Filters the post in the context of a REST request.
    506605         *
    507          * Allows plugins to filter the post object as returned by `\WP_REST_Controller::get_post()`.
     606         * Allows plugins to filter the post object as returned by WP_REST_Controller::get_post().
    508607         *
    509          * @param WP_Post|null $post_obj  The post object as returned by `get_post()`.
    510          * @param int|WP_Post  $post      The original value used to obtain the post object.
     608         * @since 4.7.0
     609         *
     610         * @param WP_Post|null $post_obj The post object as returned by get_post().
     611         * @param int|WP_Post  $post     The original value used to obtain the post object.
    511612         */
    512613        $post = apply_filters( 'rest_the_post', $post_obj, $post );
    … …  
    516617
    517618    /**
    518      * Sanitize the slug value.
    519      *
    520      * @internal We can't use {@see sanitize_title} directly, as the second
     619     * Sanitizes the slug value.
     620     *
     621     * @since 4.7.0
     622     * @access public
     623     *
     624     * @internal We can't use sanitize_title() directly, as the second
    521625     * parameter is the fallback title, which would end up being set to the
    522626     * request object.
     627     *
    523628     * @see https://github.com/WP-API/WP-API/issues/1585
    524629     *
Note: See TracChangeset for help on using the changeset viewer.