[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/rest-api/endpoints/ -> class-wp-rest-revisions-controller.php (source)

   1  <?php
   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   */
  17  class WP_REST_Revisions_Controller extends WP_REST_Controller {
  18  
  19      /**
  20       * Parent post type.
  21       *
  22       * @since 4.7.0
  23       * @var string
  24       */
  25      private $parent_post_type;
  26  
  27      /**
  28       * Instance of a revision meta fields object.
  29       *
  30       * @since 6.4.0
  31       * @var WP_REST_Post_Meta_Fields
  32       */
  33      protected $meta;
  34  
  35      /**
  36       * Parent controller.
  37       *
  38       * @since 4.7.0
  39       * @var WP_REST_Controller
  40       */
  41      private $parent_controller;
  42  
  43      /**
  44       * The base of the parent controller's route.
  45       *
  46       * @since 4.7.0
  47       * @var string
  48       */
  49      private $parent_base;
  50  
  51      /**
  52       * Constructor.
  53       *
  54       * @since 4.7.0
  55       *
  56       * @param string $parent_post_type Post type of the parent.
  57       */
  58  	public function __construct( $parent_post_type ) {
  59          $this->parent_post_type = $parent_post_type;
  60          $post_type_object       = get_post_type_object( $parent_post_type );
  61          $parent_controller      = $post_type_object->get_rest_controller();
  62  
  63          if ( ! $parent_controller ) {
  64              $parent_controller = new WP_REST_Posts_Controller( $parent_post_type );
  65          }
  66  
  67          $this->parent_controller = $parent_controller;
  68          $this->rest_base         = 'revisions';
  69          $this->parent_base       = ! empty( $post_type_object->rest_base ) ? $post_type_object->rest_base : $post_type_object->name;
  70          $this->namespace         = ! empty( $post_type_object->rest_namespace ) ? $post_type_object->rest_namespace : 'wp/v2';
  71          $this->meta              = new WP_REST_Post_Meta_Fields( $parent_post_type );
  72      }
  73  
  74      /**
  75       * Registers the routes for revisions based on post types supporting revisions.
  76       *
  77       * @since 4.7.0
  78       *
  79       * @see register_rest_route()
  80       */
  81  	public function register_routes() {
  82  
  83          register_rest_route(
  84              $this->namespace,
  85              '/' . $this->parent_base . '/(?P<parent>[\d]+)/' . $this->rest_base,
  86              array(
  87                  'args'   => array(
  88                      'parent' => array(
  89                          'description' => __( 'The ID for the parent of the revision.' ),
  90                          'type'        => 'integer',
  91                      ),
  92                  ),
  93                  array(
  94                      'methods'             => WP_REST_Server::READABLE,
  95                      'callback'            => array( $this, 'get_items' ),
  96                      'permission_callback' => array( $this, 'get_items_permissions_check' ),
  97                      'args'                => $this->get_collection_params(),
  98                  ),
  99                  'schema' => array( $this, 'get_public_item_schema' ),
 100              )
 101          );
 102  
 103          register_rest_route(
 104              $this->namespace,
 105              '/' . $this->parent_base . '/(?P<parent>[\d]+)/' . $this->rest_base . '/(?P<id>[\d]+)',
 106              array(
 107                  'args'   => array(
 108                      'parent' => array(
 109                          'description' => __( 'The ID for the parent of the revision.' ),
 110                          'type'        => 'integer',
 111                      ),
 112                      'id'     => array(
 113                          'description' => __( 'Unique identifier for the revision.' ),
 114                          'type'        => 'integer',
 115                      ),
 116                  ),
 117                  array(
 118                      'methods'             => WP_REST_Server::READABLE,
 119                      'callback'            => array( $this, 'get_item' ),
 120                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
 121                      'args'                => array(
 122                          'context' => $this->get_context_param( array( 'default' => 'view' ) ),
 123                      ),
 124                  ),
 125                  array(
 126                      'methods'             => WP_REST_Server::DELETABLE,
 127                      'callback'            => array( $this, 'delete_item' ),
 128                      'permission_callback' => array( $this, 'delete_item_permissions_check' ),
 129                      'args'                => array(
 130                          'force' => array(
 131                              'type'        => 'boolean',
 132                              'default'     => false,
 133                              'description' => __( 'Required to be true, as revisions do not support trashing.' ),
 134                          ),
 135                      ),
 136                  ),
 137                  'schema' => array( $this, 'get_public_item_schema' ),
 138              )
 139          );
 140      }
 141  
 142      /**
 143       * Get the parent post, if the ID is valid.
 144       *
 145       * @since 4.7.2
 146       *
 147       * @param int $parent_post_id Supplied ID.
 148       * @return WP_Post|WP_Error Post object if ID is valid, WP_Error otherwise.
 149       */
 150  	protected function get_parent( $parent_post_id ) {
 151          $error = new WP_Error(
 152              'rest_post_invalid_parent',
 153              __( 'Invalid post parent ID.' ),
 154              array( 'status' => 404 )
 155          );
 156  
 157          if ( (int) $parent_post_id <= 0 ) {
 158              return $error;
 159          }
 160  
 161          $parent_post = get_post( (int) $parent_post_id );
 162  
 163          if ( empty( $parent_post ) || empty( $parent_post->ID )
 164              || $this->parent_post_type !== $parent_post->post_type
 165          ) {
 166              return $error;
 167          }
 168  
 169          return $parent_post;
 170      }
 171  
 172      /**
 173       * Checks if a given request has access to get revisions.
 174       *
 175       * @since 4.7.0
 176       *
 177       * @param WP_REST_Request $request Full details about the request.
 178       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
 179       */
 180  	public function get_items_permissions_check( $request ) {
 181          $parent = $this->get_parent( $request['parent'] );
 182          if ( is_wp_error( $parent ) ) {
 183              return $parent;
 184          }
 185  
 186          if ( ! current_user_can( 'edit_post', $parent->ID ) ) {
 187              return new WP_Error(
 188                  'rest_cannot_read',
 189                  __( 'Sorry, you are not allowed to view revisions of this post.' ),
 190                  array( 'status' => rest_authorization_required_code() )
 191              );
 192          }
 193  
 194          return true;
 195      }
 196  
 197      /**
 198       * Get the revision, if the ID is valid.
 199       *
 200       * @since 4.7.2
 201       *
 202       * @param int $id Supplied ID.
 203       * @return WP_Post|WP_Error Revision post object if ID is valid, WP_Error otherwise.
 204       */
 205  	protected function get_revision( $id ) {
 206          $error = new WP_Error(
 207              'rest_post_invalid_id',
 208              __( 'Invalid revision ID.' ),
 209              array( 'status' => 404 )
 210          );
 211  
 212          if ( (int) $id <= 0 ) {
 213              return $error;
 214          }
 215  
 216          $revision = get_post( (int) $id );
 217          if ( empty( $revision ) || empty( $revision->ID ) || 'revision' !== $revision->post_type ) {
 218              return $error;
 219          }
 220  
 221          return $revision;
 222      }
 223  
 224      /**
 225       * Gets a collection of revisions.
 226       *
 227       * @since 4.7.0
 228       *
 229       * @param WP_REST_Request $request Full details about the request.
 230       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 231       */
 232  	public function get_items( $request ) {
 233          $parent = $this->get_parent( $request['parent'] );
 234          if ( is_wp_error( $parent ) ) {
 235              return $parent;
 236          }
 237  
 238          // Ensure a search string is set in case the orderby is set to 'relevance'.
 239          if ( ! empty( $request['orderby'] ) && 'relevance' === $request['orderby'] && empty( $request['search'] ) ) {
 240              return new WP_Error(
 241                  'rest_no_search_term_defined',
 242                  __( 'You need to define a search term to order by relevance.' ),
 243                  array( 'status' => 400 )
 244              );
 245          }
 246  
 247          // Ensure an include parameter is set in case the orderby is set to 'include'.
 248          if ( ! empty( $request['orderby'] ) && 'include' === $request['orderby'] && empty( $request['include'] ) ) {
 249              return new WP_Error(
 250                  'rest_orderby_include_missing_include',
 251                  __( 'You need to define an include parameter to order by include.' ),
 252                  array( 'status' => 400 )
 253              );
 254          }
 255  
 256          if ( wp_revisions_enabled( $parent ) ) {
 257              $registered = $this->get_collection_params();
 258              $args       = array(
 259                  'post_parent'      => $parent->ID,
 260                  'post_type'        => 'revision',
 261                  'post_status'      => 'inherit',
 262                  'posts_per_page'   => -1,
 263                  'orderby'          => 'date ID',
 264                  'order'            => 'DESC',
 265                  'suppress_filters' => true,
 266              );
 267  
 268              $parameter_mappings = array(
 269                  'exclude'  => 'post__not_in',
 270                  'include'  => 'post__in',
 271                  'offset'   => 'offset',
 272                  'order'    => 'order',
 273                  'orderby'  => 'orderby',
 274                  'page'     => 'paged',
 275                  'per_page' => 'posts_per_page',
 276                  'search'   => 's',
 277              );
 278  
 279              foreach ( $parameter_mappings as $api_param => $wp_param ) {
 280                  if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {
 281                      $args[ $wp_param ] = $request[ $api_param ];
 282                  }
 283              }
 284  
 285              // For backward-compatibility, 'date' needs to resolve to 'date ID'.
 286              if ( isset( $args['orderby'] ) && 'date' === $args['orderby'] ) {
 287                  $args['orderby'] = 'date ID';
 288              }
 289  
 290              /** This filter is documented in wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php */
 291              $args       = apply_filters( 'rest_revision_query', $args, $request );
 292              $query_args = $this->prepare_items_query( $args, $request );
 293  
 294              $revisions_query = new WP_Query();
 295              $revisions       = $revisions_query->query( $query_args );
 296              $offset          = isset( $query_args['offset'] ) ? (int) $query_args['offset'] : 0;
 297              $page            = (int) $query_args['paged'];
 298              $total_revisions = $revisions_query->found_posts;
 299  
 300              if ( $total_revisions < 1 ) {
 301                  // Out-of-bounds, run the query again without LIMIT for total count.
 302                  unset( $query_args['paged'], $query_args['offset'] );
 303  
 304                  $count_query = new WP_Query();
 305                  $count_query->query( $query_args );
 306  
 307                  $total_revisions = $count_query->found_posts;
 308              }
 309  
 310              if ( $revisions_query->query_vars['posts_per_page'] > 0 ) {
 311                  $max_pages = (int) ceil( $total_revisions / (int) $revisions_query->query_vars['posts_per_page'] );
 312              } else {
 313                  $max_pages = $total_revisions > 0 ? 1 : 0;
 314              }
 315  
 316              if ( $total_revisions > 0 ) {
 317                  if ( $offset >= $total_revisions ) {
 318                      return new WP_Error(
 319                          'rest_revision_invalid_offset_number',
 320                          __( 'The offset number requested is larger than or equal to the number of available revisions.' ),
 321                          array( 'status' => 400 )
 322                      );
 323                  } elseif ( ! $offset && $page > $max_pages ) {
 324                      return new WP_Error(
 325                          'rest_revision_invalid_page_number',
 326                          __( 'The page number requested is larger than the number of pages available.' ),
 327                          array( 'status' => 400 )
 328                      );
 329                  }
 330              }
 331          } else {
 332              $revisions       = array();
 333              $total_revisions = 0;
 334              $max_pages       = 0;
 335              $page            = (int) $request['page'];
 336          }
 337  
 338          $response = array();
 339  
 340          foreach ( $revisions as $revision ) {
 341              $data       = $this->prepare_item_for_response( $revision, $request );
 342              $response[] = $this->prepare_response_for_collection( $data );
 343          }
 344  
 345          $response = rest_ensure_response( $response );
 346  
 347          $response->header( 'X-WP-Total', (int) $total_revisions );
 348          $response->header( 'X-WP-TotalPages', (int) $max_pages );
 349  
 350          $request_params = $request->get_query_params();
 351          $base_path      = rest_url( sprintf( '%s/%s/%d/%s', $this->namespace, $this->parent_base, $request['parent'], $this->rest_base ) );
 352          $base           = add_query_arg( urlencode_deep( $request_params ), $base_path );
 353  
 354          if ( $page > 1 ) {
 355              $prev_page = $page - 1;
 356  
 357              if ( $prev_page > $max_pages ) {
 358                  $prev_page = $max_pages;
 359              }
 360  
 361              $prev_link = add_query_arg( 'page', $prev_page, $base );
 362              $response->link_header( 'prev', $prev_link );
 363          }
 364          if ( $max_pages > $page ) {
 365              $next_page = $page + 1;
 366              $next_link = add_query_arg( 'page', $next_page, $base );
 367  
 368              $response->link_header( 'next', $next_link );
 369          }
 370  
 371          return $response;
 372      }
 373  
 374      /**
 375       * Checks if a given request has access to get a specific revision.
 376       *
 377       * @since 4.7.0
 378       *
 379       * @param WP_REST_Request $request Full details about the request.
 380       * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
 381       */
 382  	public function get_item_permissions_check( $request ) {
 383          return $this->get_items_permissions_check( $request );
 384      }
 385  
 386      /**
 387       * Retrieves one revision from the collection.
 388       *
 389       * @since 4.7.0
 390       * @since 6.5.0 Added a condition to check that parent id matches revision parent id.
 391       *
 392       * @param WP_REST_Request $request Full details about the request.
 393       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 394       */
 395  	public function get_item( $request ) {
 396          $parent = $this->get_parent( $request['parent'] );
 397          if ( is_wp_error( $parent ) ) {
 398              return $parent;
 399          }
 400  
 401          $revision = $this->get_revision( $request['id'] );
 402          if ( is_wp_error( $revision ) ) {
 403              return $revision;
 404          }
 405  
 406          if ( (int) $parent->ID !== (int) $revision->post_parent ) {
 407              return new WP_Error(
 408                  'rest_revision_parent_id_mismatch',
 409                  /* translators: %d: A post id. */
 410                  sprintf( __( 'The revision does not belong to the specified parent with id of "%d"' ), $parent->ID ),
 411                  array( 'status' => 404 )
 412              );
 413          }
 414  
 415          $response = $this->prepare_item_for_response( $revision, $request );
 416          return rest_ensure_response( $response );
 417      }
 418  
 419      /**
 420       * Checks if a given request has access to delete a revision.
 421       *
 422       * @since 4.7.0
 423       *
 424       * @param WP_REST_Request $request Full details about the request.
 425       * @return true|WP_Error True if the request has access to delete the item, WP_Error object otherwise.
 426       */
 427  	public function delete_item_permissions_check( $request ) {
 428          $parent = $this->get_parent( $request['parent'] );
 429          if ( is_wp_error( $parent ) ) {
 430              return $parent;
 431          }
 432  
 433          if ( ! current_user_can( 'delete_post', $parent->ID ) ) {
 434              return new WP_Error(
 435                  'rest_cannot_delete',
 436                  __( 'Sorry, you are not allowed to delete revisions of this post.' ),
 437                  array( 'status' => rest_authorization_required_code() )
 438              );
 439          }
 440  
 441          $revision = $this->get_revision( $request['id'] );
 442          if ( is_wp_error( $revision ) ) {
 443              return $revision;
 444          }
 445  
 446          $response = $this->get_items_permissions_check( $request );
 447          if ( ! $response || is_wp_error( $response ) ) {
 448              return $response;
 449          }
 450  
 451          if ( ! current_user_can( 'delete_post', $revision->ID ) ) {
 452              return new WP_Error(
 453                  'rest_cannot_delete',
 454                  __( 'Sorry, you are not allowed to delete this revision.' ),
 455                  array( 'status' => rest_authorization_required_code() )
 456              );
 457          }
 458  
 459          return true;
 460      }
 461  
 462      /**
 463       * Deletes a single revision.
 464       *
 465       * @since 4.7.0
 466       *
 467       * @param WP_REST_Request $request Full details about the request.
 468       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 469       */
 470  	public function delete_item( $request ) {
 471          $revision = $this->get_revision( $request['id'] );
 472          if ( is_wp_error( $revision ) ) {
 473              return $revision;
 474          }
 475  
 476          $force = isset( $request['force'] ) ? (bool) $request['force'] : false;
 477  
 478          // We don't support trashing for revisions.
 479          if ( ! $force ) {
 480              return new WP_Error(
 481                  'rest_trash_not_supported',
 482                  /* translators: %s: force=true */
 483                  sprintf( __( "Revisions do not support trashing. Set '%s' to delete." ), 'force=true' ),
 484                  array( 'status' => 501 )
 485              );
 486          }
 487  
 488          $previous = $this->prepare_item_for_response( $revision, $request );
 489  
 490          $result = wp_delete_post( $request['id'], true );
 491  
 492          /**
 493           * Fires after a revision is deleted via the REST API.
 494           *
 495           * @since 4.7.0
 496           *
 497           * @param WP_Post|false|null $result The revision object (if it was deleted or moved to the Trash successfully)
 498           *                                   or false or null (failure). If the revision was moved to the Trash, $result represents
 499           *                                   its new state; if it was deleted, $result represents its state before deletion.
 500           * @param WP_REST_Request $request The request sent to the API.
 501           */
 502          do_action( 'rest_delete_revision', $result, $request );
 503  
 504          if ( ! $result ) {
 505              return new WP_Error(
 506                  'rest_cannot_delete',
 507                  __( 'The post cannot be deleted.' ),
 508                  array( 'status' => 500 )
 509              );
 510          }
 511  
 512          $response = new WP_REST_Response();
 513          $response->set_data(
 514              array(
 515                  'deleted'  => true,
 516                  'previous' => $previous->get_data(),
 517              )
 518          );
 519          return $response;
 520      }
 521  
 522      /**
 523       * Determines the allowed query_vars for a get_items() response and prepares
 524       * them for WP_Query.
 525       *
 526       * @since 5.0.0
 527       *
 528       * @param array           $prepared_args Optional. Prepared WP_Query arguments. Default empty array.
 529       * @param WP_REST_Request $request       Optional. Full details about the request.
 530       * @return array Items query arguments.
 531       */
 532  	protected function prepare_items_query( $prepared_args = array(), $request = null ) {
 533          $query_args = array();
 534  
 535          foreach ( $prepared_args as $key => $value ) {
 536              /** This filter is documented in wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php */
 537              $query_args[ $key ] = apply_filters( "rest_query_var-{$key}", $value ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores
 538          }
 539  
 540          // Map to proper WP_Query orderby param.
 541          if ( isset( $query_args['orderby'] ) && isset( $request['orderby'] ) ) {
 542              $orderby_mappings = array(
 543                  'id'            => 'ID',
 544                  'include'       => 'post__in',
 545                  'slug'          => 'post_name',
 546                  'include_slugs' => 'post_name__in',
 547              );
 548  
 549              if ( isset( $orderby_mappings[ $request['orderby'] ] ) ) {
 550                  $query_args['orderby'] = $orderby_mappings[ $request['orderby'] ];
 551              }
 552          }
 553  
 554          return $query_args;
 555      }
 556  
 557      /**
 558       * Prepares the revision for the REST response.
 559       *
 560       * @since 4.7.0
 561       * @since 5.9.0 Renamed `$post` to `$item` to match parent class for PHP 8 named parameter support.
 562       *
 563       * @global WP_Post $post Global post object.
 564       *
 565       * @param WP_Post         $item    Post revision object.
 566       * @param WP_REST_Request $request Request object.
 567       * @return WP_REST_Response Response object.
 568       */
 569  	public function prepare_item_for_response( $item, $request ) {
 570          // Restores the more descriptive, specific name for use within this method.
 571          $post = $item;
 572  
 573          $GLOBALS['post'] = $post;
 574  
 575          setup_postdata( $post );
 576  
 577          $fields = $this->get_fields_for_response( $request );
 578          $data   = array();
 579  
 580          if ( in_array( 'author', $fields, true ) ) {
 581              $data['author'] = (int) $post->post_author;
 582          }
 583  
 584          if ( in_array( 'date', $fields, true ) ) {
 585              $data['date'] = $this->prepare_date_response( $post->post_date_gmt, $post->post_date );
 586          }
 587  
 588          if ( in_array( 'date_gmt', $fields, true ) ) {
 589              $data['date_gmt'] = $this->prepare_date_response( $post->post_date_gmt );
 590          }
 591  
 592          if ( in_array( 'id', $fields, true ) ) {
 593              $data['id'] = $post->ID;
 594          }
 595  
 596          if ( in_array( 'modified', $fields, true ) ) {
 597              $data['modified'] = $this->prepare_date_response( $post->post_modified_gmt, $post->post_modified );
 598          }
 599  
 600          if ( in_array( 'modified_gmt', $fields, true ) ) {
 601              $data['modified_gmt'] = $this->prepare_date_response( $post->post_modified_gmt );
 602          }
 603  
 604          if ( in_array( 'parent', $fields, true ) ) {
 605              $data['parent'] = (int) $post->post_parent;
 606          }
 607  
 608          if ( in_array( 'slug', $fields, true ) ) {
 609              $data['slug'] = $post->post_name;
 610          }
 611  
 612          if ( in_array( 'guid', $fields, true ) ) {
 613              $data['guid'] = array(
 614                  /** This filter is documented in wp-includes/post-template.php */
 615                  'rendered' => apply_filters( 'get_the_guid', $post->guid, $post->ID ),
 616                  'raw'      => $post->guid,
 617              );
 618          }
 619  
 620          if ( in_array( 'title', $fields, true ) ) {
 621              $data['title'] = array(
 622                  'raw'      => $post->post_title,
 623                  'rendered' => get_the_title( $post->ID ),
 624              );
 625          }
 626  
 627          if ( in_array( 'content', $fields, true ) ) {
 628  
 629              $data['content'] = array(
 630                  'raw'      => $post->post_content,
 631                  /** This filter is documented in wp-includes/post-template.php */
 632                  'rendered' => apply_filters( 'the_content', $post->post_content ),
 633              );
 634          }
 635  
 636          if ( in_array( 'excerpt', $fields, true ) ) {
 637              $data['excerpt'] = array(
 638                  'raw'      => $post->post_excerpt,
 639                  'rendered' => $this->prepare_excerpt_response( $post->post_excerpt, $post ),
 640              );
 641          }
 642  
 643          if ( rest_is_field_included( 'meta', $fields ) ) {
 644              $data['meta'] = $this->meta->get_value( $post->ID, $request );
 645          }
 646  
 647          $context  = ! empty( $request['context'] ) ? $request['context'] : 'view';
 648          $data     = $this->add_additional_fields_to_object( $data, $request );
 649          $data     = $this->filter_response_by_context( $data, $context );
 650          $response = rest_ensure_response( $data );
 651  
 652          if ( ! empty( $data['parent'] ) ) {
 653              $response->add_link( 'parent', rest_url( rest_get_route_for_post( $data['parent'] ) ) );
 654          }
 655  
 656          /**
 657           * Filters a revision returned from the REST API.
 658           *
 659           * Allows modification of the revision right before it is returned.
 660           *
 661           * @since 4.7.0
 662           *
 663           * @param WP_REST_Response $response The response object.
 664           * @param WP_Post          $post     The original revision object.
 665           * @param WP_REST_Request  $request  Request used to generate the response.
 666           */
 667          return apply_filters( 'rest_prepare_revision', $response, $post, $request );
 668      }
 669  
 670      /**
 671       * Checks the post_date_gmt or modified_gmt and prepare any post or
 672       * modified date for single post output.
 673       *
 674       * @since 4.7.0
 675       *
 676       * @param string      $date_gmt GMT publication time.
 677       * @param string|null $date     Optional. Local publication time. Default null.
 678       * @return string|null ISO8601/RFC3339 formatted datetime, otherwise null.
 679       */
 680  	protected function prepare_date_response( $date_gmt, $date = null ) {
 681          if ( '0000-00-00 00:00:00' === $date_gmt ) {
 682              return null;
 683          }
 684  
 685          if ( isset( $date ) ) {
 686              return mysql_to_rfc3339( $date );
 687          }
 688  
 689          return mysql_to_rfc3339( $date_gmt );
 690      }
 691  
 692      /**
 693       * Retrieves the revision's schema, conforming to JSON Schema.
 694       *
 695       * @since 4.7.0
 696       *
 697       * @return array Item schema data.
 698       */
 699  	public function get_item_schema() {
 700          if ( $this->schema ) {
 701              return $this->add_additional_fields_schema( $this->schema );
 702          }
 703  
 704          $schema = array(
 705              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 706              'title'      => "{$this->parent_post_type}-revision",
 707              'type'       => 'object',
 708              // Base properties for every Revision.
 709              'properties' => array(
 710                  'author'       => array(
 711                      'description' => __( 'The ID for the author of the revision.' ),
 712                      'type'        => 'integer',
 713                      'context'     => array( 'view', 'edit', 'embed' ),
 714                  ),
 715                  'date'         => array(
 716                      'description' => __( "The date the revision was published, in the site's timezone." ),
 717                      'type'        => 'string',
 718                      'format'      => 'date-time',
 719                      'context'     => array( 'view', 'edit', 'embed' ),
 720                  ),
 721                  'date_gmt'     => array(
 722                      'description' => __( 'The date the revision was published, as GMT.' ),
 723                      'type'        => 'string',
 724                      'format'      => 'date-time',
 725                      'context'     => array( 'view', 'edit' ),
 726                  ),
 727                  'guid'         => array(
 728                      'description' => __( 'GUID for the revision, as it exists in the database.' ),
 729                      'type'        => 'string',
 730                      'context'     => array( 'view', 'edit' ),
 731                  ),
 732                  'id'           => array(
 733                      'description' => __( 'Unique identifier for the revision.' ),
 734                      'type'        => 'integer',
 735                      'context'     => array( 'view', 'edit', 'embed' ),
 736                  ),
 737                  'modified'     => array(
 738                      'description' => __( "The date the revision was last modified, in the site's timezone." ),
 739                      'type'        => 'string',
 740                      'format'      => 'date-time',
 741                      'context'     => array( 'view', 'edit' ),
 742                  ),
 743                  'modified_gmt' => array(
 744                      'description' => __( 'The date the revision was last modified, as GMT.' ),
 745                      'type'        => 'string',
 746                      'format'      => 'date-time',
 747                      'context'     => array( 'view', 'edit' ),
 748                  ),
 749                  'parent'       => array(
 750                      'description' => __( 'The ID for the parent of the revision.' ),
 751                      'type'        => 'integer',
 752                      'context'     => array( 'view', 'edit', 'embed' ),
 753                  ),
 754                  'slug'         => array(
 755                      'description' => __( 'An alphanumeric identifier for the revision unique to its type.' ),
 756                      'type'        => 'string',
 757                      'context'     => array( 'view', 'edit', 'embed' ),
 758                  ),
 759              ),
 760          );
 761  
 762          $parent_schema = $this->parent_controller->get_item_schema();
 763  
 764          if ( ! empty( $parent_schema['properties']['title'] ) ) {
 765              $schema['properties']['title'] = $parent_schema['properties']['title'];
 766          }
 767  
 768          if ( ! empty( $parent_schema['properties']['content'] ) ) {
 769              $schema['properties']['content'] = $parent_schema['properties']['content'];
 770          }
 771  
 772          if ( ! empty( $parent_schema['properties']['excerpt'] ) ) {
 773              $schema['properties']['excerpt'] = $parent_schema['properties']['excerpt'];
 774          }
 775  
 776          if ( ! empty( $parent_schema['properties']['guid'] ) ) {
 777              $schema['properties']['guid'] = $parent_schema['properties']['guid'];
 778          }
 779  
 780          $schema['properties']['meta'] = $this->meta->get_field_schema();
 781  
 782          $this->schema = $schema;
 783  
 784          return $this->add_additional_fields_schema( $this->schema );
 785      }
 786  
 787      /**
 788       * Retrieves the query params for collections.
 789       *
 790       * @since 4.7.0
 791       *
 792       * @return array Collection parameters.
 793       */
 794  	public function get_collection_params() {
 795          $query_params = parent::get_collection_params();
 796  
 797          $query_params['context']['default'] = 'view';
 798  
 799          unset( $query_params['per_page']['default'] );
 800  
 801          $query_params['exclude'] = array(
 802              'description' => __( 'Ensure result set excludes specific IDs.' ),
 803              'type'        => 'array',
 804              'items'       => array(
 805                  'type' => 'integer',
 806              ),
 807              'default'     => array(),
 808          );
 809  
 810          $query_params['include'] = array(
 811              'description' => __( 'Limit result set to specific IDs.' ),
 812              'type'        => 'array',
 813              'items'       => array(
 814                  'type' => 'integer',
 815              ),
 816              'default'     => array(),
 817          );
 818  
 819          $query_params['offset'] = array(
 820              'description' => __( 'Offset the result set by a specific number of items.' ),
 821              'type'        => 'integer',
 822          );
 823  
 824          $query_params['order'] = array(
 825              'description' => __( 'Order sort attribute ascending or descending.' ),
 826              'type'        => 'string',
 827              'default'     => 'desc',
 828              'enum'        => array( 'asc', 'desc' ),
 829          );
 830  
 831          $query_params['orderby'] = array(
 832              'description' => __( 'Sort collection by object attribute.' ),
 833              'type'        => 'string',
 834              'default'     => 'date',
 835              'enum'        => array(
 836                  'date',
 837                  'id',
 838                  'include',
 839                  'relevance',
 840                  'slug',
 841                  'include_slugs',
 842                  'title',
 843              ),
 844          );
 845  
 846          return $query_params;
 847      }
 848  
 849      /**
 850       * Checks the post excerpt and prepare it for single post output.
 851       *
 852       * @since 4.7.0
 853       *
 854       * @param string  $excerpt The post excerpt.
 855       * @param WP_Post $post    Post revision object.
 856       * @return string Prepared excerpt or empty string.
 857       */
 858  	protected function prepare_excerpt_response( $excerpt, $post ) {
 859  
 860          /** This filter is documented in wp-includes/post-template.php */
 861          $excerpt = apply_filters( 'the_excerpt', $excerpt, $post );
 862  
 863          if ( empty( $excerpt ) ) {
 864              return '';
 865          }
 866  
 867          return $excerpt;
 868      }
 869  }


Generated : Tue Dec 24 08:20:01 2024 Cross-referenced by PHPXref