WordPress.org
Get WordPress

Make WordPress Core

Changeset 39024


Ignore:
Timestamp:
10/30/2016 04:43:12 PM (8 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.