WordPress.org
Get WordPress

Make WordPress Core

Changeset 39025


Ignore:
Timestamp:
10/30/2016 04:50:15 PM (10 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.