WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
10/30/2016 04:43:12 PM (10 years ago)
Author:
DrewAPicture
Message:

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

    r38832 r39024  
    11<?php
    2 
     2/**
     3 * REST API: WP_REST_Post_Statuses_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
     9
     10/**
     11 * Core class used to access post statuses via the REST API.
     12 *
     13 * @since 4.7.0
     14 *
     15 * @see WP_REST_Controller
     16 */
    317class WP_REST_Post_Statuses_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(),
     45                                'args'                => $this->get_collection_params(),
    2146                        ),
    2247                        'schema' => array( $this, 'get_public_item_schema' ),
    … …  
    2550                register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<status>[\w-]+)', array(
    2651                        array(
    27                                 'methods'         => WP_REST_Server::READABLE,
    28                                 'callback'        => array( $this, 'get_item' ),
     52                                'methods'             => WP_REST_Server::READABLE,
     53                                'callback'            => array( $this, 'get_item' ),
    2954                                'permission_callback' => array( $this, 'get_item_permissions_check' ),
    30                                 'args'            => array(
    31                                         'context'          => $this->get_context_param( array( 'default' => 'view' ) ),
     55                                'args'                => array(
     56                                        'context' => $this->get_context_param( array( 'default' => 'view' ) ),
    3257                                ),
    3358                        ),
    … …  
    3762
    3863        /**
    39          * Check whether a given request has permission to read post statuses.
    40          *
    41          * @param  WP_REST_Request $request Full details about the request.
    42          * @return WP_Error|boolean
     64         * Checks whether a given request has permission to read post statuses.
     65         *
     66         * @since 4.7.0
     67         * @access public
     68         *
     69         * @param WP_REST_Request $request Full details about the request.
     70         * @return WP_Error|bool True if the request has read access, WP_Error object otherwise.
    4371         */
    4472        public function get_items_permissions_check( $request ) {
    4573                if ( 'edit' === $request['context'] ) {
    4674                        $types = get_post_types( array( 'show_in_rest' => true ), 'objects' );
     75
    4776                        foreach ( $types as $type ) {
    4877                                if ( current_user_can( $type->cap->edit_posts ) ) {
    … …  
    5281                        return new WP_Error( 'rest_cannot_view', __( 'Sorry, you cannot view this resource with edit context.' ), array( 'status' => rest_authorization_required_code() ) );
    5382                }
     83
    5484                return true;
    5585        }
    5686
    5787        /**
    58          * Get all post statuses, depending on user context
    59          *
    60          * @param WP_REST_Request $request
    61          * @return array|WP_Error
     88         * Retrieves all post statuses, depending on user context.
     89         *
     90         * @since 4.7.0
     91         * @access public
     92         *
     93         * @param WP_REST_Request $request Full details about the request.
     94         * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    6295         */
    6396        public function get_items( $request ) {
    … …  
    6598                $statuses = get_post_stati( array( 'internal' => false ), 'object' );
    6699                $statuses['trash'] = get_post_status_object( 'trash' );
     100
    67101                foreach ( $statuses as $slug => $obj ) {
    68102                        $ret = $this->check_read_permission( $obj );
     103
    69104                        if ( ! $ret ) {
    70105                                continue;
    71106                        }
     107
    72108                        $status = $this->prepare_item_for_response( $obj, $request );
    73109                        $data[ $obj->name ] = $this->prepare_response_for_collection( $status );
    74110                }
     111
    75112                return rest_ensure_response( $data );
    76113        }
    77114
    78115        /**
    79          * Check if a given request has access to read a post status.
    80          *
    81          * @param  WP_REST_Request $request Full details about the request.
    82          * @return WP_Error|boolean
     116         * Checks if a given request has access to read a post status.
     117         *
     118         * @since 4.7.0
     119         * @access public
     120         *
     121         * @param WP_REST_Request $request Full details about the request.
     122         * @return WP_Error|bool True if the request has read access for the item, WP_Error object otherwise.
    83123         */
    84124        public function get_item_permissions_check( $request ) {
    85125                $status = get_post_status_object( $request['status'] );
     126
    86127                if ( empty( $status ) ) {
    87128                        return new WP_Error( 'rest_status_invalid', __( 'Invalid resource.' ), array( 'status' => 404 ) );
    88129                }
     130
    89131                $check = $this->check_read_permission( $status );
     132
    90133                if ( ! $check ) {
    91134                        return new WP_Error( 'rest_cannot_read_status', __( 'Cannot view resource.' ), array( 'status' => rest_authorization_required_code() ) );
    92135                }
     136
    93137                return true;
    94138        }
    95139
    96140        /**
    97          * Check whether a given post status should be visible
    98          *
    99          * @param object $status
    100          * @return boolean
     141         * Checks whether a given post status should be visible.
     142         *
     143         * @since 4.7.0
     144         * @access protected
     145         *
     146         * @param object $status Post status.
     147         * @return bool True if the post status is visible, otherwise false.
    101148         */
    102149        protected function check_read_permission( $status ) {
    … …  
    104151                        return true;
    105152                }
     153
    106154                if ( false === $status->internal || 'trash' === $status->name ) {
    107155                        $types = get_post_types( array( 'show_in_rest' => true ), 'objects' );
     156
    108157                        foreach ( $types as $type ) {
    109158                                if ( current_user_can( $type->cap->edit_posts ) ) {
    … …  
    112161                        }
    113162                }
     163
    114164                return false;
    115165        }
    116166
    117167        /**
    118          * Get a specific post status
    119          *
    120          * @param WP_REST_Request $request
    121          * @return array|WP_Error
     168         * Retrieves a specific post status.
     169         *
     170         * @since 4.7.0
     171         * @access public
     172         *
     173         * @param WP_REST_Request $request Full details about the request.
     174         * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
    122175         */
    123176        public function get_item( $request ) {
    124177                $obj = get_post_status_object( $request['status'] );
     178
    125179                if ( empty( $obj ) ) {
    126180                        return new WP_Error( 'rest_status_invalid', __( 'Invalid resource.' ), array( 'status' => 404 ) );
    127181                }
     182
    128183                $data = $this->prepare_item_for_response( $obj, $request );
     184
    129185                return rest_ensure_response( $data );
    130186        }
    131187
    132188        /**
    133          * Prepare a post status object for serialization
    134          *
    135          * @param stdClass $status Post status data
    136          * @param WP_REST_Request $request
    137          * @return WP_REST_Response Post status data
     189         * Prepares a post status object for serialization.
     190         *
     191         * @since 4.7.0
     192         * @access public
     193         *
     194         * @param stdClass        $status  Post status data.
     195         * @param WP_REST_Request $request Full details about the request.
     196         * @return WP_REST_Response Post status data.
    138197         */
    139198        public function prepare_item_for_response( $status, $request ) {
    … …  
    162221
    163222                /**
    164                  * Filter a status returned from the API.
     223                 * Filters a status returned from the REST API.
    165224                 *
    166225                 * Allows modification of the status data right before it is returned.
    167226                 *
    168                  * @param WP_REST_Response  $response The response object.
    169                  * @param object            $status   The original status object.
    170                  * @param WP_REST_Request   $request  Request used to generate the response.
     227                 * @since 4.7.0
     228                 *
     229                 * @param WP_REST_Response $response The response object.
     230                 * @param object           $status   The original status object.
     231                 * @param WP_REST_Request  $request  Request used to generate the response.
    171232                 */
    172233                return apply_filters( 'rest_prepare_status', $response, $status, $request );
    … …  
    174235
    175236        /**
    176          * Get the Post status' schema, conforming to JSON Schema
    177          *
    178          * @return array
     237         * Retrieves the post status' schema, conforming to JSON Schema.
     238         *
     239         * @since 4.7.0
     240         * @access public
     241         *
     242         * @return array Item schema data.
    179243         */
    180244        public function get_item_schema() {
    … …  
    228292                        ),
    229293                );
     294
    230295                return $this->add_additional_fields_schema( $schema );
    231296        }
    232297
    233298        /**
    234          * Get the query params for collections
    235          *
    236          * @return array
     299         * Retrieves the query params for collections.
     300         *
     301         * @since 4.7.0
     302         * @access public
     303         *
     304         * @return array Collection parameters.
    237305         */
    238306        public function get_collection_params() {
    239307                return array(
    240                         'context'        => $this->get_context_param( array( 'default' => 'view' ) ),
     308                        'context' => $this->get_context_param( array( 'default' => 'view' ) ),
    241309                );
    242310        }
Note: See TracChangeset for help on using the changeset viewer.