WordPress.org

Make WordPress Core

Changeset 39025


Ignore:
Timestamp:
10/30/2016 04:50:15 PM (4 years ago)
Author:
DrewAPicture
Message:

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

    r38832 r39025  
    11<?php
    2 
     2/**
     3 * REST API: WP_REST_Post_Types_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
     9
     10/**
     11 * Core class to access post types via the REST API.
     12 *
     13 * @since 4.7.0
     14 *
     15 * @see WP_REST_Controller
     16 */
    317class WP_REST_Post_Types_Controller extends WP_REST_Controller {
    418
     19    /**
     20     * Constructor.
     21     *
     22     * @since 4.7.0
     23     * @access public
     24     */
    525    public function __construct() {
    626        $this->namespace = 'wp/v2';
     
    929
    1030    /**
    11      * 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()
    1237     */
    1338    public function register_routes() {
     
    1540        register_rest_route( $this->namespace, '/' . $this->rest_base, array(
    1641            array(
    17                 'methods'         => WP_REST_Server::READABLE,
    18                 'callback'        => array( $this, 'get_items' ),
     42                'methods'             => WP_REST_Server::READABLE,
     43                'callback'            => array( $this, 'get_items' ),
    1944                'permission_callback' => array( $this, 'get_items_permissions_check' ),
    20                 'args'            => $this->get_collection_params(),
    21             ),
    22             'schema'          => array( $this, 'get_public_item_schema' ),
     45                'args'                => $this->get_collection_params(),
     46            ),
     47            'schema' => array( $this, 'get_public_item_schema' ),
    2348        ) );
    2449
    2550        register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<type>[\w-]+)', array(
    2651            array(
    27                 'methods'         => WP_REST_Server::READABLE,
    28                 'callback'        => array( $this, 'get_item' ),
    29                 'args'            => array(
    30                     'context'     => $this->get_context_param( array( 'default' => 'view' ) ),
    31                 ),
    32             ),
    33             'schema'          => array( $this, 'get_public_item_schema' ),
     52                'methods'  => WP_REST_Server::READABLE,
     53                'callback' => array( $this, 'get_item' ),
     54                'args'     => array(
     55                    'context' => $this->get_context_param( array( 'default' => 'view' ) ),
     56                ),
     57            ),
     58            'schema' => array( $this, 'get_public_item_schema' ),
    3459        ) );
    3560    }
    3661
    3762    /**
    38      * Check whether a given request has permission to read types.
    39      *
    40      * @param  WP_REST_Request $request Full details about the request.
    41      * @return WP_Error|boolean
     63     * Checks whether a given request has permission to read types.
     64     *
     65     * @since 4.7.0
     66     * @access public
     67     *
     68     * @param WP_REST_Request $request Full details about the request.
     69     * @return WP_Error|true True if the request has read access, WP_Error object otherwise.
    4270     */
    4371    public function get_items_permissions_check( $request ) {
     
    4876                }
    4977            }
     78
    5079            return new WP_Error( 'rest_cannot_view', __( 'Sorry, you cannot view this resource with edit context.' ), array( 'status' => rest_authorization_required_code() ) );
    5180        }
     81
    5282        return true;
    5383    }
    5484
    5585    /**
    56      * Get all public post types
    57      *
    58      * @param WP_REST_Request $request
    59      * @return array|WP_Error
     86     * Retrieves all public post types.
     87     *
     88     * @since 4.7.0
     89     * @access public
     90     *
     91     * @param WP_REST_Request $request Full details about the request.
     92     * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    6093     */
    6194    public function get_items( $request ) {
    6295        $data = array();
     96
    6397        foreach ( get_post_types( array(), 'object' ) as $obj ) {
    6498            if ( empty( $obj->show_in_rest ) || ( 'edit' === $request['context'] && ! current_user_can( $obj->cap->edit_posts ) ) ) {
    6599                continue;
    66100            }
     101
    67102            $post_type = $this->prepare_item_for_response( $obj, $request );
    68103            $data[ $obj->name ] = $this->prepare_response_for_collection( $post_type );
    69104        }
     105
    70106        return rest_ensure_response( $data );
    71107    }
    72108
    73109    /**
    74      * Get a specific post type
    75      *
    76      * @param WP_REST_Request $request
    77      * @return array|WP_Error
     110     * Retrieves a specific post type.
     111     *
     112     * @since 4.7.0
     113     * @access public
     114     *
     115     * @param WP_REST_Request $request Full details about the request.
     116     * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    78117     */
    79118    public function get_item( $request ) {
    80119        $obj = get_post_type_object( $request['type'] );
     120
    81121        if ( empty( $obj ) ) {
    82122            return new WP_Error( 'rest_type_invalid', __( 'Invalid resource.' ), array( 'status' => 404 ) );
    83123        }
     124
    84125        if ( empty( $obj->show_in_rest ) ) {
    85126            return new WP_Error( 'rest_cannot_read_type', __( 'Cannot view resource.' ), array( 'status' => rest_authorization_required_code() ) );
    86127        }
     128
    87129        if ( 'edit' === $request['context'] && ! current_user_can( $obj->cap->edit_posts ) ) {
    88130            return new WP_Error( 'rest_forbidden_context', __( 'Sorry, you are not allowed to manage this resource.' ), array( 'status' => rest_authorization_required_code() ) );
    89131        }
     132
    90133        $data = $this->prepare_item_for_response( $obj, $request );
     134
    91135        return rest_ensure_response( $data );
    92136    }
    93137
    94138    /**
    95      * Prepare a post type object for serialization
    96      *
    97      * @param stdClass $post_type Post type data
    98      * @param WP_REST_Request $request
    99      * @return WP_REST_Response $response
     139     * Prepares a post type object for serialization.
     140     *
     141     * @since 4.7.0
     142     * @access public
     143     *
     144     * @param stdClass        $post_type Post type data.
     145     * @param WP_REST_Request $request   Full details about the request.
     146     * @return WP_REST_Response Response object.
    100147     */
    101148    public function prepare_item_for_response( $post_type, $request ) {
     
    109156        );
    110157        $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
    111         $data = $this->add_additional_fields_to_object( $data, $request );
    112         $data = $this->filter_response_by_context( $data, $context );
     158        $data    = $this->add_additional_fields_to_object( $data, $request );
     159        $data    = $this->filter_response_by_context( $data, $context );
    113160
    114161        // Wrap the data in a response object.
     
    116163
    117164        $base = ! empty( $post_type->rest_base ) ? $post_type->rest_base : $post_type->name;
     165
    118166        $response->add_links( array(
    119             'collection'              => array(
    120                 'href'                => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
     167            'collection' => array(
     168                'href'   => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
    121169            ),
    122170            'https://api.w.org/items' => array(
    123                 'href'                => rest_url( sprintf( 'wp/v2/%s', $base ) ),
     171                'href' => rest_url( sprintf( 'wp/v2/%s', $base ) ),
    124172            ),
    125173        ) );
    126174
    127175        /**
    128          * Filter a post type returned from the API.
     176         * Filters a post type returned from the API.
    129177         *
    130178         * Allows modification of the post type data right before it is returned.
    131179         *
    132          * @param WP_REST_Response  $response   The response object.
    133          * @param object            $item       The original post type object.
    134          * @param WP_REST_Request   $request    Request used to generate the response.
     180         * @since 4.7.0
     181         *
     182         * @param WP_REST_Response $response The response object.
     183         * @param object           $item     The original post type object.
     184         * @param WP_REST_Request  $request  Request used to generate the response.
    135185         */
    136186        return apply_filters( 'rest_prepare_post_type', $response, $post_type, $request );
     
    138188
    139189    /**
    140      * Get the Post type's schema, conforming to JSON Schema
    141      *
    142      * @return array
     190     * Retrieves the post type's schema, conforming to JSON Schema.
     191     *
     192     * @since 4.7.0
     193     * @access public
     194     *
     195     * @return array Item schema data.
    143196     */
    144197    public function get_item_schema() {
     
    190243
    191244    /**
    192      * Get the query params for collections
    193      *
    194      * @return array
     245     * Retrieves the query params for collections.
     246     *
     247     * @since 4.7.0
     248     * @access public
     249     *
     250     * @return array Collection parameters.
    195251     */
    196252    public function get_collection_params() {
    197253        return array(
    198             'context'      => $this->get_context_param( array( 'default' => 'view' ) ),
     254            'context' => $this->get_context_param( array( 'default' => 'view' ) ),
    199255        );
    200256    }
Note: See TracChangeset for help on using the changeset viewer.