[Summary view] [Print] [Text view]

   1  <?php
   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   */
  17  class WP_REST_Post_Statuses_Controller extends WP_REST_Controller {
  18  
  19      /**
  20       * Constructor.
  21       *
  22       * @since 4.7.0
  23       */
  24  	public function __construct() {
  25          $this->namespace = 'wp/v2';
  26          $this->rest_base = 'statuses';
  27      }
  28  
  29      /**
  30       * Registers the routes for post statuses.
  31       *
  32       * @since 4.7.0
  33       *
  34       * @see register_rest_route()
  35       */
  36  	public function register_routes() {
  37  
  38          register_rest_route(
  39              $this->namespace,
  40              '/' . $this->rest_base,
  41              array(
  42                  array(
  43                      'methods'             => WP_REST_Server::READABLE,
  44                      'callback'            => array( $this, 'get_items' ),
  45                      'permission_callback' => array( $this, 'get_items_permissions_check' ),
  46                      'args'                => $this->get_collection_params(),
  47                  ),
  48                  'schema' => array( $this, 'get_public_item_schema' ),
  49              )
  50          );
  51  
  52          register_rest_route(
  53              $this->namespace,
  54              '/' . $this->rest_base . '/(?P<status>[\w-]+)',
  55              array(
  56                  'args'   => array(
  57                      'status' => array(
  58                          'description' => __( 'An alphanumeric identifier for the status.' ),
  59                          'type'        => 'string',
  60                      ),
  61                  ),
  62                  array(
  63                      'methods'             => WP_REST_Server::READABLE,
  64                      'callback'            => array( $this, 'get_item' ),
  65                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
  66                      'args'                => array(
  67                          'context' => $this->get_context_param( array( 'default' => 'view' ) ),
  68                      ),
  69                  ),
  70                  'schema' => array( $this, 'get_public_item_schema' ),
  71              )
  72          );
  73      }
  74  
  75      /**
  76       * Checks whether a given request has permission to read post statuses.
  77       *
  78       * @since 4.7.0
  79       *
  80       * @param WP_REST_Request $request Full details about the request.
  81       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
  82       */
  83  	public function get_items_permissions_check( $request ) {
  84          if ( 'edit' === $request['context'] ) {
  85              $types = get_post_types( array( 'show_in_rest' => true ), 'objects' );
  86  
  87              foreach ( $types as $type ) {
  88                  if ( current_user_can( $type->cap->edit_posts ) ) {
  89                      return true;
  90                  }
  91              }
  92  
  93              return new WP_Error(
  94                  'rest_cannot_view',
  95                  __( 'Sorry, you are not allowed to manage post statuses.' ),
  96                  array( 'status' => rest_authorization_required_code() )
  97              );
  98          }
  99  
 100          return true;
 101      }
 102  
 103      /**
 104       * Retrieves all post statuses, depending on user context.
 105       *
 106       * @since 4.7.0
 107       *
 108       * @param WP_REST_Request $request Full details about the request.
 109       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 110       */
 111  	public function get_items( $request ) {
 112          $data              = array();
 113          $statuses          = get_post_stati( array( 'internal' => false ), 'object' );
 114          $statuses['trash'] = get_post_status_object( 'trash' );
 115  
 116          foreach ( $statuses as $slug => $obj ) {
 117              $ret = $this->check_read_permission( $obj );
 118  
 119              if ( ! $ret ) {
 120                  continue;
 121              }
 122  
 123              $status             = $this->prepare_item_for_response( $obj, $request );
 124              $data[ $obj->name ] = $this->prepare_response_for_collection( $status );
 125          }
 126  
 127          return rest_ensure_response( $data );
 128      }
 129  
 130      /**
 131       * Checks if a given request has access to read a post status.
 132       *
 133       * @since 4.7.0
 134       *
 135       * @param WP_REST_Request $request Full details about the request.
 136       * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
 137       */
 138  	public function get_item_permissions_check( $request ) {
 139          $status = get_post_status_object( $request['status'] );
 140  
 141          if ( empty( $status ) ) {
 142              return new WP_Error(
 143                  'rest_status_invalid',
 144                  __( 'Invalid status.' ),
 145                  array( 'status' => 404 )
 146              );
 147          }
 148  
 149          $check = $this->check_read_permission( $status );
 150  
 151          if ( ! $check ) {
 152              return new WP_Error(
 153                  'rest_cannot_read_status',
 154                  __( 'Cannot view status.' ),
 155                  array( 'status' => rest_authorization_required_code() )
 156              );
 157          }
 158  
 159          return true;
 160      }
 161  
 162      /**
 163       * Checks whether a given post status should be visible.
 164       *
 165       * @since 4.7.0
 166       *
 167       * @param object $status Post status.
 168       * @return bool True if the post status is visible, otherwise false.
 169       */
 170  	protected function check_read_permission( $status ) {
 171          if ( true === $status->public ) {
 172              return true;
 173          }
 174  
 175          if ( false === $status->internal || 'trash' === $status->name ) {
 176              $types = get_post_types( array( 'show_in_rest' => true ), 'objects' );
 177  
 178              foreach ( $types as $type ) {
 179                  if ( current_user_can( $type->cap->edit_posts ) ) {
 180                      return true;
 181                  }
 182              }
 183          }
 184  
 185          return false;
 186      }
 187  
 188      /**
 189       * Retrieves a specific post status.
 190       *
 191       * @since 4.7.0
 192       *
 193       * @param WP_REST_Request $request Full details about the request.
 194       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 195       */
 196  	public function get_item( $request ) {
 197          $obj = get_post_status_object( $request['status'] );
 198  
 199          if ( empty( $obj ) ) {
 200              return new WP_Error(
 201                  'rest_status_invalid',
 202                  __( 'Invalid status.' ),
 203                  array( 'status' => 404 )
 204              );
 205          }
 206  
 207          $data = $this->prepare_item_for_response( $obj, $request );
 208  
 209          return rest_ensure_response( $data );
 210      }
 211  
 212      /**
 213       * Prepares a post status object for serialization.
 214       *
 215       * @since 4.7.0
 216       * @since 5.9.0 Renamed `$status` to `$item` to match parent class for PHP 8 named parameter support.
 217       *
 218       * @param stdClass        $item    Post status data.
 219       * @param WP_REST_Request $request Full details about the request.
 220       * @return WP_REST_Response Post status data.
 221       */
 222  	public function prepare_item_for_response( $item, $request ) {
 223          // Restores the more descriptive, specific name for use within this method.
 224          $status = $item;
 225          $fields = $this->get_fields_for_response( $request );
 226          $data   = array();
 227  
 228          if ( in_array( 'name', $fields, true ) ) {
 229              $data['name'] = $status->label;
 230          }
 231  
 232          if ( in_array( 'private', $fields, true ) ) {
 233              $data['private'] = (bool) $status->private;
 234          }
 235  
 236          if ( in_array( 'protected', $fields, true ) ) {
 237              $data['protected'] = (bool) $status->protected;
 238          }
 239  
 240          if ( in_array( 'public', $fields, true ) ) {
 241              $data['public'] = (bool) $status->public;
 242          }
 243  
 244          if ( in_array( 'queryable', $fields, true ) ) {
 245              $data['queryable'] = (bool) $status->publicly_queryable;
 246          }
 247  
 248          if ( in_array( 'show_in_list', $fields, true ) ) {
 249              $data['show_in_list'] = (bool) $status->show_in_admin_all_list;
 250          }
 251  
 252          if ( in_array( 'slug', $fields, true ) ) {
 253              $data['slug'] = $status->name;
 254          }
 255  
 256          if ( in_array( 'date_floating', $fields, true ) ) {
 257              $data['date_floating'] = $status->date_floating;
 258          }
 259  
 260          $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
 261          $data    = $this->add_additional_fields_to_object( $data, $request );
 262          $data    = $this->filter_response_by_context( $data, $context );
 263  
 264          $response = rest_ensure_response( $data );
 265  
 266          $rest_url = rest_url( rest_get_route_for_post_type_items( 'post' ) );
 267          if ( 'publish' === $status->name ) {
 268              $response->add_link( 'archives', $rest_url );
 269          } else {
 270              $response->add_link( 'archives', add_query_arg( 'status', $status->name, $rest_url ) );
 271          }
 272  
 273          /**
 274           * Filters a post status returned from the REST API.
 275           *
 276           * Allows modification of the status data right before it is returned.
 277           *
 278           * @since 4.7.0
 279           *
 280           * @param WP_REST_Response $response The response object.
 281           * @param object           $status   The original post status object.
 282           * @param WP_REST_Request  $request  Request used to generate the response.
 283           */
 284          return apply_filters( 'rest_prepare_status', $response, $status, $request );
 285      }
 286  
 287      /**
 288       * Retrieves the post status' schema, conforming to JSON Schema.
 289       *
 290       * @since 4.7.0
 291       *
 292       * @return array Item schema data.
 293       */
 294  	public function get_item_schema() {
 295          if ( $this->schema ) {
 296              return $this->add_additional_fields_schema( $this->schema );
 297          }
 298  
 299          $schema = array(
 300              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 301              'title'      => 'status',
 302              'type'       => 'object',
 303              'properties' => array(
 304                  'name'          => array(
 305                      'description' => __( 'The title for the status.' ),
 306                      'type'        => 'string',
 307                      'context'     => array( 'embed', 'view', 'edit' ),
 308                      'readonly'    => true,
 309                  ),
 310                  'private'       => array(
 311                      'description' => __( 'Whether posts with this status should be private.' ),
 312                      'type'        => 'boolean',
 313                      'context'     => array( 'edit' ),
 314                      'readonly'    => true,
 315                  ),
 316                  'protected'     => array(
 317                      'description' => __( 'Whether posts with this status should be protected.' ),
 318                      'type'        => 'boolean',
 319                      'context'     => array( 'edit' ),
 320                      'readonly'    => true,
 321                  ),
 322                  'public'        => array(
 323                      'description' => __( 'Whether posts of this status should be shown in the front end of the site.' ),
 324                      'type'        => 'boolean',
 325                      'context'     => array( 'view', 'edit' ),
 326                      'readonly'    => true,
 327                  ),
 328                  'queryable'     => array(
 329                      'description' => __( 'Whether posts with this status should be publicly-queryable.' ),
 330                      'type'        => 'boolean',
 331                      'context'     => array( 'view', 'edit' ),
 332                      'readonly'    => true,
 333                  ),
 334                  'show_in_list'  => array(
 335                      'description' => __( 'Whether to include posts in the edit listing for their post type.' ),
 336                      'type'        => 'boolean',
 337                      'context'     => array( 'edit' ),
 338                      'readonly'    => true,
 339                  ),
 340                  'slug'          => array(
 341                      'description' => __( 'An alphanumeric identifier for the status.' ),
 342                      'type'        => 'string',
 343                      'context'     => array( 'embed', 'view', 'edit' ),
 344                      'readonly'    => true,
 345                  ),
 346                  'date_floating' => array(
 347                      'description' => __( 'Whether posts of this status may have floating published dates.' ),
 348                      'type'        => 'boolean',
 349                      'context'     => array( 'view', 'edit' ),
 350                      'readonly'    => true,
 351                  ),
 352              ),
 353          );
 354  
 355          $this->schema = $schema;
 356  
 357          return $this->add_additional_fields_schema( $this->schema );
 358      }
 359  
 360      /**
 361       * Retrieves the query params for collections.
 362       *
 363       * @since 4.7.0
 364       *
 365       * @return array Collection parameters.
 366       */
 367  	public function get_collection_params() {
 368          return array(
 369              'context' => $this->get_context_param( array( 'default' => 'view' ) ),
 370          );
 371      }
 372  
 373  }