sergiotarxz
/
Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Docs: Add much more complete and syntactically correct documentation throughout the `WP_REST_Revisions_Controller` class. 

Props Soean, mrahmadawais, flixos90.
See #38398.


git-svn-id: https://develop.svn.wordpress.org/trunk@39028 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Drew Jaynes 2016-10-30 17:49:14 +00:00
parent d10a54f83c
commit 5fdf3ac313
1 changed files with 104 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
src/wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php
View File

@ -1,11 +1,56 @@
<?php <?php
/**
* REST API: WP_REST_Revisions_Controller class
*
* @package WordPress
* @subpackage REST_API
* @since 4.7.0
*/
/**
* Core class used to access revisions via the REST API.
*
* @since 4.7.0
*
* @see WP_REST_Controller
*/
class WP_REST_Revisions_Controller extends WP_REST_Controller { class WP_REST_Revisions_Controller extends WP_REST_Controller {
/**
* Parent post type.
*
* @since 4.7.0
* @access private
* @var string
*/
private $parent_post_type; private $parent_post_type;
/**
* Parent controller.
*
* @since 4.7.0
* @access private
* @var WP_REST_Controller
*/
private $parent_controller; private $parent_controller;
/**
* The base of the parent controller's route.
*
* @since 4.7.0
* @access private
* @var string
*/
private $parent_base; private $parent_base;
/**
* Constructor.
*
* @since 4.7.0
* @access public
*
* @param string $parent_post_type Post type of the parent.
*/
public function __construct( $parent_post_type ) { public function __construct( $parent_post_type ) {
$this->parent_post_type = $parent_post_type; $this->parent_post_type = $parent_post_type;
$this->parent_controller = new WP_REST_Posts_Controller( $parent_post_type ); $this->parent_controller = new WP_REST_Posts_Controller( $parent_post_type );
@ -16,34 +61,37 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Register routes for revisions based on post types supporting revisions * Registers routes for revisions based on post types supporting revisions.
* *
* @since 4.7.0
* @access public * @access public
*
* @see register_rest_route()
*/ */
public function register_routes() { public function register_routes() {
register_rest_route( $this->namespace, '/' . $this->parent_base . '/(?P<parent>[\d]+)/' . $this->rest_base, array( register_rest_route( $this->namespace, '/' . $this->parent_base . '/(?P<parent>[\d]+)/' . $this->rest_base, array(
array( array(
'methods' => WP_REST_Server::READABLE, 'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_items' ), 'callback' => array( $this, 'get_items' ),
'permission_callback' => array( $this, 'get_items_permissions_check' ), 'permission_callback' => array( $this, 'get_items_permissions_check' ),
'args' => $this->get_collection_params(), 'args' => $this->get_collection_params(),
), ),
'schema' => array( $this, 'get_public_item_schema' ), 'schema' => array( $this, 'get_public_item_schema' ),
) ); ) );
register_rest_route( $this->namespace, '/' . $this->parent_base . '/(?P<parent>[\d]+)/' . $this->rest_base . '/(?P<id>[\d]+)', array( register_rest_route( $this->namespace, '/' . $this->parent_base . '/(?P<parent>[\d]+)/' . $this->rest_base . '/(?P<id>[\d]+)', array(
array( array(
'methods' => WP_REST_Server::READABLE, 'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_item' ), 'callback' => array( $this, 'get_item' ),
'permission_callback' => array( $this, 'get_item_permissions_check' ), 'permission_callback' => array( $this, 'get_item_permissions_check' ),
'args' => array( 'args' => array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ), 'context' => $this->get_context_param( array( 'default' => 'view' ) ),
), ),
), ),
array( array(
'methods' => WP_REST_Server::DELETABLE, 'methods' => WP_REST_Server::DELETABLE,
'callback' => array( $this, 'delete_item' ), 'callback' => array( $this, 'delete_item' ),
'permission_callback' => array( $this, 'delete_item_permissions_check' ), 'permission_callback' => array( $this, 'delete_item_permissions_check' ),
), ),
'schema' => array( $this, 'get_public_item_schema' ), 'schema' => array( $this, 'get_public_item_schema' ),
@ -52,12 +100,13 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Check if a given request has access to get revisions * Checks if a given request has access to get revisions.
* *
* @since 4.7.0
* @access public * @access public
* *
* @param WP_REST_Request $request Full data about the request. * @param WP_REST_Request $request Full data about the request.
* @return WP_Error|boolean * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/ */
public function get_items_permissions_check( $request ) { public function get_items_permissions_check( $request ) {
@ -74,12 +123,13 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Get a collection of revisions * Gets a collection of revisions.
* *
* @since 4.7.0
* @access public * @access public
* *
* @param WP_REST_Request $request Full data about the request. * @param WP_REST_Request $request Full data about the request.
* @return WP_Error|WP_REST_Response * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/ */
public function get_items( $request ) { public function get_items( $request ) {
@ -99,24 +149,26 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Check if a given request has access to get a specific revision * Checks if a given request has access to get a specific revision.
* *
* @since 4.7.0
* @access public * @access public
* *
* @param WP_REST_Request $request Full data about the request. * @param WP_REST_Request $request Full data about the request.
* @return WP_Error|boolean * @return bool|WP_Error True if the request has read access for the item, WP_Error object otherwise.
*/ */
public function get_item_permissions_check( $request ) { public function get_item_permissions_check( $request ) {
return $this->get_items_permissions_check( $request ); return $this->get_items_permissions_check( $request );
} }
/** /**
* Get one revision from the collection * Retrieves one revision from the collection.
* *
* @since 4.7.0
* @access public * @access public
* *
* @param WP_REST_Request $request Full data about the request. * @param WP_REST_Request $request Full data about the request.
* @return WP_Error|array * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/ */
public function get_item( $request ) { public function get_item( $request ) {
@ -135,12 +187,13 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Check if a given request has access to delete a revision * Checks if a given request has access to delete a revision.
* *
* @since 4.7.0
* @access public * @access public
* *
* @param WP_REST_Request $request Full details about the request. * @param WP_REST_Request $request Full details about the request.
* @return WP_Error|boolean * @return bool|WP_Error True if the request has access to delete the item, WP_Error object otherwise.
*/ */
public function delete_item_permissions_check( $request ) { public function delete_item_permissions_check( $request ) {
@ -158,12 +211,13 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Delete a single revision * Deletes a single revision.
* *
* @since 4.7.0
* @access public * @access public
* *
* @param WP_REST_Request $request Full details about the request. * @param WP_REST_Request $request Full details about the request.
* @return WP_Error|boolean * @return true|WP_Error True on success, or WP_Error object on failure.
*/ */
public function delete_item( $request ) { public function delete_item( $request ) {
$result = wp_delete_post( $request['id'], true ); $result = wp_delete_post( $request['id'], true );
@ -171,6 +225,8 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
/** /**
* Fires after a revision is deleted via the REST API. * Fires after a revision is deleted via the REST API.
* *
* @since 4.7.0
*
* @param (mixed) $result The revision object (if it was deleted or moved to the trash successfully) * @param (mixed) $result The revision object (if it was deleted or moved to the trash successfully)
* or false (failure). If the revision was moved to to the trash, $result represents * or false (failure). If the revision was moved to to the trash, $result represents
* its new state; if it was deleted, $result represents its state before deletion. * its new state; if it was deleted, $result represents its state before deletion.
@ -186,13 +242,14 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Prepare the revision for the REST response * Prepares the revision for the REST response.
* *
* @since 4.7.0
* @access public * @access public
* *
* @param WP_Post $post Post revision object. * @param WP_Post $post Post revision object.
* @param WP_REST_Request $request Request object. * @param WP_REST_Request $request Request object.
* @return WP_REST_Response $response * @return WP_REST_Response Response object.
*/ */
public function prepare_item_for_response( $post, $request ) { public function prepare_item_for_response( $post, $request ) {
@ -273,26 +330,29 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Filter a revision returned from the API. * Filters a revision returned from the API.
* *
* Allows modification of the revision right before it is returned. * Allows modification of the revision right before it is returned.
* *
* @param WP_REST_Response $response The response object. * @since 4.7.0
* @param WP_Post $post The original revision object. *
* @param WP_REST_Request $request Request used to generate the response. * @param WP_REST_Response $response The response object.
* @param WP_Post $post The original revision object.
* @param WP_REST_Request $request Request used to generate the response.
*/ */
return apply_filters( 'rest_prepare_revision', $response, $post, $request ); return apply_filters( 'rest_prepare_revision', $response, $post, $request );
} }
/** /**
* Check the post_date_gmt or modified_gmt and prepare any post or * Checks the post_date_gmt or modified_gmt and prepare any post or
* modified date for single post output. * modified date for single post output.
* *
* @since 4.7.0
* @access protected * @access protected
* *
* @param string $date_gmt GMT publication time. * @param string $date_gmt GMT publication time.
* @param string|null $date Optional, default is null. Local publication time. * @param string|null $date Optional. Local publication time. Default null.
* @return string|null ISO8601/RFC3339 formatted datetime. * @return string|null ISO8601/RFC3339 formatted datetime, otherwise null.
*/ */
protected function prepare_date_response( $date_gmt, $date = null ) { protected function prepare_date_response( $date_gmt, $date = null ) {
if ( '0000-00-00 00:00:00' === $date_gmt ) { if ( '0000-00-00 00:00:00' === $date_gmt ) {
@ -307,20 +367,19 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Get the revision's schema, conforming to JSON Schema * Retrieves the revision's schema, conforming to JSON Schema.
* *
* @since 4.7.0
* @access public * @access public
* *
* @return array * @return array Item schema data.
*/ */
public function get_item_schema() { public function get_item_schema() {
$schema = array( $schema = array(
'$schema' => 'http://json-schema.org/draft-04/schema#', '$schema' => 'http://json-schema.org/draft-04/schema#',
'title' => "{$this->parent_post_type}-revision", 'title' => "{$this->parent_post_type}-revision",
'type' => 'object', 'type' => 'object',
/* // Base properties for every Revision.
* Base properties for every Revision
*/
'properties' => array( 'properties' => array(
'author' => array( 'author' => array(
'description' => __( 'The id for the author of the object.' ), 'description' => __( 'The id for the author of the object.' ),
@ -379,12 +438,15 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
if ( ! empty( $parent_schema['properties']['title'] ) ) { if ( ! empty( $parent_schema['properties']['title'] ) ) {
$schema['properties']['title'] = $parent_schema['properties']['title']; $schema['properties']['title'] = $parent_schema['properties']['title'];
} }
if ( ! empty( $parent_schema['properties']['content'] ) ) { if ( ! empty( $parent_schema['properties']['content'] ) ) {
$schema['properties']['content'] = $parent_schema['properties']['content']; $schema['properties']['content'] = $parent_schema['properties']['content'];
} }
if ( ! empty( $parent_schema['properties']['excerpt'] ) ) { if ( ! empty( $parent_schema['properties']['excerpt'] ) ) {
$schema['properties']['excerpt'] = $parent_schema['properties']['excerpt']; $schema['properties']['excerpt'] = $parent_schema['properties']['excerpt'];
} }
if ( ! empty( $parent_schema['properties']['guid'] ) ) { if ( ! empty( $parent_schema['properties']['guid'] ) ) {
$schema['properties']['guid'] = $parent_schema['properties']['guid']; $schema['properties']['guid'] = $parent_schema['properties']['guid'];
} }
@ -393,11 +455,12 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Get the query params for collections * Retrieves the query params for collections.
* *
* @since 4.7.0
* @access public * @access public
* *
* @return array * @return array Collection parameters.
*/ */
public function get_collection_params() { public function get_collection_params() {
return array( return array(
@ -406,13 +469,14 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
} }
/** /**
* Check the post excerpt and prepare it for single post output. * Checks the post excerpt and prepare it for single post output.
* *
* @since 4.7.0
* @access protected * @access protected
* *
* @param string $excerpt The post excerpt. * @param string $excerpt The post excerpt.
* @param WP_Post $post Post revision object. * @param WP_Post $post Post revision object.
* @return string|null $excerpt * @return string Prepared excerpt or empty string.
*/ */
protected function prepare_excerpt_response( $excerpt, $post ) { protected function prepare_excerpt_response( $excerpt, $post ) {