WordPress.org
Get WordPress

Make WordPress Core

Changeset 39028


Ignore:
Timestamp:
10/30/2016 05:49:14 PM (7 years ago)
Author:
DrewAPicture
Message:

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

    r38832 r39028  
    11<?php
    2 
     2/**
     3 * REST API: WP_REST_Revisions_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
     9
     10/**
     11 * Core class used to access revisions via the REST API.
     12 *
     13 * @since 4.7.0
     14 *
     15 * @see WP_REST_Controller
     16 */
    317class WP_REST_Revisions_Controller extends WP_REST_Controller {
    418
     19    /**
     20     * Parent post type.
     21     *
     22     * @since 4.7.0
     23     * @access private
     24     * @var string
     25     */
    526    private $parent_post_type;
     27
     28    /**
     29     * Parent controller.
     30     *
     31     * @since 4.7.0
     32     * @access private
     33     * @var WP_REST_Controller
     34     */
    635    private $parent_controller;
     36
     37    /**
     38     * The base of the parent controller's route.
     39     *
     40     * @since 4.7.0
     41     * @access private
     42     * @var string
     43     */
    744    private $parent_base;
    845
     46    /**
     47     * Constructor.
     48     *
     49     * @since 4.7.0
     50     * @access public
     51     *
     52     * @param string $parent_post_type Post type of the parent.
     53     */
    954    public function __construct( $parent_post_type ) {
    1055        $this->parent_post_type = $parent_post_type;
    … …  
    1762
    1863    /**
    19      * Register routes for revisions based on post types supporting revisions
    20      *
    21      * @access public
     64     * Registers routes for revisions based on post types supporting revisions.
     65     *
     66     * @since 4.7.0
     67     * @access public
     68     *
     69     * @see register_rest_route()
    2270     */
    2371    public function register_routes() {
    … …  
    2573        register_rest_route( $this->namespace, '/' . $this->parent_base . '/(?P<parent>[\d]+)/' . $this->rest_base, array(
    2674            array(
    27                 'methods'         => WP_REST_Server::READABLE,
    28                 'callback'        => array( $this, 'get_items' ),
     75                'methods'             => WP_REST_Server::READABLE,
     76                'callback'            => array( $this, 'get_items' ),
    2977                'permission_callback' => array( $this, 'get_items_permissions_check' ),
    30                 'args'            => $this->get_collection_params(),
     78                'args'                => $this->get_collection_params(),
    3179            ),
    3280            'schema' => array( $this, 'get_public_item_schema' ),
    … …  
    3583        register_rest_route( $this->namespace, '/' . $this->parent_base . '/(?P<parent>[\d]+)/' . $this->rest_base . '/(?P<id>[\d]+)', array(
    3684            array(
    37                 'methods'         => WP_REST_Server::READABLE,
    38                 'callback'        => array( $this, 'get_item' ),
     85                'methods'             => WP_REST_Server::READABLE,
     86                'callback'            => array( $this, 'get_item' ),
    3987                'permission_callback' => array( $this, 'get_item_permissions_check' ),
    40                 'args'            => array(
    41                     'context'          => $this->get_context_param( array( 'default' => 'view' ) ),
     88                'args'                => array(
     89                    'context' => $this->get_context_param( array( 'default' => 'view' ) ),
    4290                ),
    4391            ),
    4492            array(
    45                 'methods'         => WP_REST_Server::DELETABLE,
    46                 'callback'        => array( $this, 'delete_item' ),
     93                'methods'             => WP_REST_Server::DELETABLE,
     94                'callback'            => array( $this, 'delete_item' ),
    4795                'permission_callback' => array( $this, 'delete_item_permissions_check' ),
    4896            ),
    … …  
    53101
    54102    /**
    55      * Check if a given request has access to get revisions
    56      *
     103     * Checks if a given request has access to get revisions.
     104     *
     105     * @since 4.7.0
    57106     * @access public
    58107     *
    59108     * @param WP_REST_Request $request Full data about the request.
    60      * @return WP_Error|boolean
     109     * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
    61110     */
    62111    public function get_items_permissions_check( $request ) {
    … …  
    75124
    76125    /**
    77      * Get a collection of revisions
    78      *
     126     * Gets a collection of revisions.
     127     *
     128     * @since 4.7.0
    79129     * @access public
    80130     *
    81131     * @param WP_REST_Request $request Full data about the request.
    82      * @return WP_Error|WP_REST_Response
     132     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    83133     */
    84134    public function get_items( $request ) {
    … …  
    100150
    101151    /**
    102      * Check if a given request has access to get a specific revision
    103      *
     152     * Checks if a given request has access to get a specific revision.
     153     *
     154     * @since 4.7.0
    104155     * @access public
    105156     *
    106157     * @param WP_REST_Request $request Full data about the request.
    107      * @return WP_Error|boolean
     158     * @return bool|WP_Error True if the request has read access for the item, WP_Error object otherwise.
    108159     */
    109160    public function get_item_permissions_check( $request ) {
    … …  
    112163
    113164    /**
    114      * Get one revision from the collection
    115      *
     165     * Retrieves one revision from the collection.
     166     *
     167     * @since 4.7.0
    116168     * @access public
    117169     *
    118170     * @param WP_REST_Request $request Full data about the request.
    119      * @return WP_Error|array
     171     * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    120172     */
    121173    public function get_item( $request ) {
    … …  
    136188
    137189    /**
    138      * Check if a given request has access to delete a revision
    139      *
     190     * Checks if a given request has access to delete a revision.
     191     *
     192     * @since 4.7.0
    140193     * @access public
    141194     *
    142195     * @param  WP_REST_Request $request Full details about the request.
    143      * @return WP_Error|boolean
     196     * @return bool|WP_Error True if the request has access to delete the item, WP_Error object otherwise.
    144197     */
    145198    public function delete_item_permissions_check( $request ) {
    … …  
    159212
    160213    /**
    161      * Delete a single revision
    162      *
     214     * Deletes a single revision.
     215     *
     216     * @since 4.7.0
    163217     * @access public
    164218     *
    165219     * @param WP_REST_Request $request Full details about the request.
    166      * @return WP_Error|boolean
     220     * @return true|WP_Error True on success, or WP_Error object on failure.
    167221     */
    168222    public function delete_item( $request ) {
    … …  
    171225        /**
    172226         * Fires after a revision is deleted via the REST API.
     227         *
     228         * @since 4.7.0
    173229         *
    174230         * @param (mixed) $result The revision object (if it was deleted or moved to the trash successfully)
    … …  
    187243
    188244    /**
    189      * Prepare the revision for the REST response
    190      *
     245     * Prepares the revision for the REST response.
     246     *
     247     * @since 4.7.0
    191248     * @access public
    192249     *
    193250     * @param WP_Post         $post    Post revision object.
    194251     * @param WP_REST_Request $request Request object.
    195      * @return WP_REST_Response $response
     252     * @return WP_REST_Response Response object.
    196253     */
    197254    public function prepare_item_for_response( $post, $request ) {
    … …  
    274331
    275332        /**
    276          * Filter a revision returned from the API.
     333         * Filters a revision returned from the API.
    277334         *
    278335         * Allows modification of the revision right before it is returned.
    279336         *
    280          * @param WP_REST_Response  $response   The response object.
    281          * @param WP_Post           $post       The original revision object.
    282          * @param WP_REST_Request   $request    Request used to generate the response.
     337         * @since 4.7.0
     338         *
     339         * @param WP_REST_Response $response The response object.
     340         * @param WP_Post          $post     The original revision object.
     341         * @param WP_REST_Request  $request  Request used to generate the response.
    283342         */
    284343        return apply_filters( 'rest_prepare_revision', $response, $post, $request );
    … …  
    286345
    287346    /**
    288      * Check the post_date_gmt or modified_gmt and prepare any post or
     347     * Checks the post_date_gmt or modified_gmt and prepare any post or
    289348     * modified date for single post output.
    290349     *
     350     * @since 4.7.0
    291351     * @access protected
    292352     *
    293353     * @param string      $date_gmt GMT publication time.
    294      * @param string|null $date     Optional, default is null. Local publication time.
    295      * @return string|null ISO8601/RFC3339 formatted datetime.
     354     * @param string|null $date     Optional. Local publication time. Default null.
     355     * @return string|null ISO8601/RFC3339 formatted datetime, otherwise null.
    296356     */
    297357    protected function prepare_date_response( $date_gmt, $date = null ) {
    … …  
    308368
    309369    /**
    310      * Get the revision's schema, conforming to JSON Schema
    311      *
    312      * @access public
    313      *
    314      * @return array
     370     * Retrieves the revision's schema, conforming to JSON Schema.
     371     *
     372     * @since 4.7.0
     373     * @access public
     374     *
     375     * @return array Item schema data.
    315376     */
    316377    public function get_item_schema() {
    … …  
    319380            'title'      => "{$this->parent_post_type}-revision",
    320381            'type'       => 'object',
    321             /*
    322              * Base properties for every Revision
    323              */
     382            // Base properties for every Revision.
    324383            'properties' => array(
    325384                'author'          => array(
    … …  
    380439            $schema['properties']['title'] = $parent_schema['properties']['title'];
    381440        }
     441
    382442        if ( ! empty( $parent_schema['properties']['content'] ) ) {
    383443            $schema['properties']['content'] = $parent_schema['properties']['content'];
    384444        }
     445
    385446        if ( ! empty( $parent_schema['properties']['excerpt'] ) ) {
    386447            $schema['properties']['excerpt'] = $parent_schema['properties']['excerpt'];
    387448        }
     449
    388450        if ( ! empty( $parent_schema['properties']['guid'] ) ) {
    389451            $schema['properties']['guid'] = $parent_schema['properties']['guid'];
    … …  
    394456
    395457    /**
    396      * Get the query params for collections
    397      *
    398      * @access public
    399      *
    400      * @return array
     458     * Retrieves the query params for collections.
     459     *
     460     * @since 4.7.0
     461     * @access public
     462     *
     463     * @return array Collection parameters.
    401464     */
    402465    public function get_collection_params() {
    … …  
    407470
    408471    /**
    409      * Check the post excerpt and prepare it for single post output.
    410      *
     472     * Checks the post excerpt and prepare it for single post output.
     473     *
     474     * @since 4.7.0
    411475     * @access protected
    412476     *
    413477     * @param string  $excerpt The post excerpt.
    414478     * @param WP_Post $post    Post revision object.
    415      * @return string|null $excerpt
     479     * @return string Prepared excerpt or empty string.
    416480     */
    417481    protected function prepare_excerpt_response( $excerpt, $post ) {
Note: See TracChangeset for help on using the changeset viewer.