WP_REST_Post_Statuses_Controller

Core class used to access post statuses via the REST API.

Defined (1)

The class is defined in the following location(s).

/wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php  
  1. class WP_REST_Post_Statuses_Controller extends WP_REST_Controller { 
  2.  
  3. /** 
  4. * Constructor. 
  5. * @since 4.7.0 
  6. * @access public 
  7. */ 
  8. public function __construct() { 
  9. $this->namespace = 'wp/v2'; 
  10. $this->rest_base = 'statuses'; 
  11.  
  12. /** 
  13. * Registers the routes for the objects of the controller. 
  14. * @since 4.7.0 
  15. * @access public 
  16. * @see register_rest_route() 
  17. */ 
  18. public function register_routes() { 
  19.  
  20. register_rest_route( $this->namespace, '/' . $this->rest_base, array( 
  21. array( 
  22. 'methods' => WP_REST_Server::READABLE,  
  23. 'callback' => array( $this, 'get_items' ),  
  24. 'permission_callback' => array( $this, 'get_items_permissions_check' ),  
  25. 'args' => $this->get_collection_params(),  
  26. ),  
  27. 'schema' => array( $this, 'get_public_item_schema' ),  
  28. ) ); 
  29.  
  30. register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<status>[\w-]+)', array( 
  31. array( 
  32. 'methods' => WP_REST_Server::READABLE,  
  33. 'callback' => array( $this, 'get_item' ),  
  34. 'permission_callback' => array( $this, 'get_item_permissions_check' ),  
  35. 'args' => array( 
  36. 'context' => $this->get_context_param( array( 'default' => 'view' ) ),  
  37. ),  
  38. ),  
  39. 'schema' => array( $this, 'get_public_item_schema' ),  
  40. ) ); 
  41.  
  42. /** 
  43. * Checks whether a given request has permission to read post statuses. 
  44. * @since 4.7.0 
  45. * @access public 
  46. * @param WP_REST_Request $request Full details about the request. 
  47. * @return WP_Error|bool True if the request has read access, WP_Error object otherwise. 
  48. */ 
  49. public function get_items_permissions_check( $request ) { 
  50. if ( 'edit' === $request['context'] ) { 
  51. $types = get_post_types( array( 'show_in_rest' => true ), 'objects' ); 
  52.  
  53. foreach ( $types as $type ) { 
  54. if ( current_user_can( $type->cap->edit_posts ) ) { 
  55. return true; 
  56. return new WP_Error( 'rest_cannot_view', __( 'Sorry, you are not allowed to edit posts in this post type.' ), array( 'status' => rest_authorization_required_code() ) ); 
  57.  
  58. return true; 
  59.  
  60. /** 
  61. * Retrieves all post statuses, depending on user context. 
  62. * @since 4.7.0 
  63. * @access public 
  64. * @param WP_REST_Request $request Full details about the request. 
  65. * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure. 
  66. */ 
  67. public function get_items( $request ) { 
  68. $data = array(); 
  69. $statuses = get_post_stati( array( 'internal' => false ), 'object' ); 
  70. $statuses['trash'] = get_post_status_object( 'trash' ); 
  71.  
  72. foreach ( $statuses as $slug => $obj ) { 
  73. $ret = $this->check_read_permission( $obj ); 
  74.  
  75. if ( ! $ret ) { 
  76. continue; 
  77.  
  78. $status = $this->prepare_item_for_response( $obj, $request ); 
  79. $data[ $obj->name ] = $this->prepare_response_for_collection( $status ); 
  80.  
  81. return rest_ensure_response( $data ); 
  82.  
  83. /** 
  84. * Checks if a given request has access to read a post status. 
  85. * @since 4.7.0 
  86. * @access public 
  87. * @param WP_REST_Request $request Full details about the request. 
  88. * @return WP_Error|bool True if the request has read access for the item, WP_Error object otherwise. 
  89. */ 
  90. public function get_item_permissions_check( $request ) { 
  91. $status = get_post_status_object( $request['status'] ); 
  92.  
  93. if ( empty( $status ) ) { 
  94. return new WP_Error( 'rest_status_invalid', __( 'Invalid status.' ), array( 'status' => 404 ) ); 
  95.  
  96. $check = $this->check_read_permission( $status ); 
  97.  
  98. if ( ! $check ) { 
  99. return new WP_Error( 'rest_cannot_read_status', __( 'Cannot view status.' ), array( 'status' => rest_authorization_required_code() ) ); 
  100.  
  101. return true; 
  102.  
  103. /** 
  104. * Checks whether a given post status should be visible. 
  105. * @since 4.7.0 
  106. * @access protected 
  107. * @param object $status Post status. 
  108. * @return bool True if the post status is visible, otherwise false. 
  109. */ 
  110. protected function check_read_permission( $status ) { 
  111. if ( true === $status->public ) { 
  112. return true; 
  113.  
  114. if ( false === $status->internal || 'trash' === $status->name ) { 
  115. $types = get_post_types( array( 'show_in_rest' => true ), 'objects' ); 
  116.  
  117. foreach ( $types as $type ) { 
  118. if ( current_user_can( $type->cap->edit_posts ) ) { 
  119. return true; 
  120.  
  121. return false; 
  122.  
  123. /** 
  124. * Retrieves a specific post status. 
  125. * @since 4.7.0 
  126. * @access public 
  127. * @param WP_REST_Request $request Full details about the request. 
  128. * @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure. 
  129. */ 
  130. public function get_item( $request ) { 
  131. $obj = get_post_status_object( $request['status'] ); 
  132.  
  133. if ( empty( $obj ) ) { 
  134. return new WP_Error( 'rest_status_invalid', __( 'Invalid status.' ), array( 'status' => 404 ) ); 
  135.  
  136. $data = $this->prepare_item_for_response( $obj, $request ); 
  137.  
  138. return rest_ensure_response( $data ); 
  139.  
  140. /** 
  141. * Prepares a post status object for serialization. 
  142. * @since 4.7.0 
  143. * @access public 
  144. * @param stdClass $status Post status data. 
  145. * @param WP_REST_Request $request Full details about the request. 
  146. * @return WP_REST_Response Post status data. 
  147. */ 
  148. public function prepare_item_for_response( $status, $request ) { 
  149.  
  150. $data = array( 
  151. 'name' => $status->label,  
  152. 'private' => (bool) $status->private,  
  153. 'protected' => (bool) $status->protected,  
  154. 'public' => (bool) $status->public,  
  155. 'queryable' => (bool) $status->publicly_queryable,  
  156. 'show_in_list' => (bool) $status->show_in_admin_all_list,  
  157. 'slug' => $status->name,  
  158. ); 
  159.  
  160. $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; 
  161. $data = $this->add_additional_fields_to_object( $data, $request ); 
  162. $data = $this->filter_response_by_context( $data, $context ); 
  163.  
  164. $response = rest_ensure_response( $data ); 
  165.  
  166. if ( 'publish' === $status->name ) { 
  167. $response->add_link( 'archives', rest_url( 'wp/v2/posts' ) ); 
  168. } else { 
  169. $response->add_link( 'archives', add_query_arg( 'status', $status->name, rest_url( 'wp/v2/posts' ) ) ); 
  170.  
  171. /** 
  172. * Filters a status returned from the REST API. 
  173. * Allows modification of the status data right before it is returned. 
  174. * @since 4.7.0 
  175. * @param WP_REST_Response $response The response object. 
  176. * @param object $status The original status object. 
  177. * @param WP_REST_Request $request Request used to generate the response. 
  178. */ 
  179. return apply_filters( 'rest_prepare_status', $response, $status, $request ); 
  180.  
  181. /** 
  182. * Retrieves the post status' schema, conforming to JSON Schema. 
  183. * @since 4.7.0 
  184. * @access public 
  185. * @return array Item schema data. 
  186. */ 
  187. public function get_item_schema() { 
  188. $schema = array( 
  189. '$schema' => 'http://json-schema.org/schema#',  
  190. 'title' => 'status',  
  191. 'type' => 'object',  
  192. 'properties' => array( 
  193. 'name' => array( 
  194. 'description' => __( 'The title for the status.' ),  
  195. 'type' => 'string',  
  196. 'context' => array( 'embed', 'view', 'edit' ),  
  197. 'readonly' => true,  
  198. ),  
  199. 'private' => array( 
  200. 'description' => __( 'Whether posts with this status should be private.' ),  
  201. 'type' => 'boolean',  
  202. 'context' => array( 'edit' ),  
  203. 'readonly' => true,  
  204. ),  
  205. 'protected' => array( 
  206. 'description' => __( 'Whether posts with this status should be protected.' ),  
  207. 'type' => 'boolean',  
  208. 'context' => array( 'edit' ),  
  209. 'readonly' => true,  
  210. ),  
  211. 'public' => array( 
  212. 'description' => __( 'Whether posts of this status should be shown in the front end of the site.' ),  
  213. 'type' => 'boolean',  
  214. 'context' => array( 'view', 'edit' ),  
  215. 'readonly' => true,  
  216. ),  
  217. 'queryable' => array( 
  218. 'description' => __( 'Whether posts with this status should be publicly-queryable.' ),  
  219. 'type' => 'boolean',  
  220. 'context' => array( 'view', 'edit' ),  
  221. 'readonly' => true,  
  222. ),  
  223. 'show_in_list' => array( 
  224. 'description' => __( 'Whether to include posts in the edit listing for their post type.' ),  
  225. 'type' => 'boolean',  
  226. 'context' => array( 'edit' ),  
  227. 'readonly' => true,  
  228. ),  
  229. 'slug' => array( 
  230. 'description' => __( 'An alphanumeric identifier for the status.' ),  
  231. 'type' => 'string',  
  232. 'context' => array( 'embed', 'view', 'edit' ),  
  233. 'readonly' => true,  
  234. ),  
  235. ),  
  236. ); 
  237.  
  238. return $this->add_additional_fields_schema( $schema ); 
  239.  
  240. /** 
  241. * Retrieves the query params for collections. 
  242. * @since 4.7.0 
  243. * @access public 
  244. * @return array Collection parameters. 
  245. */ 
  246. public function get_collection_params() { 
  247. return array( 
  248. 'context' => $this->get_context_param( array( 'default' => 'view' ) ),  
  249. ); 
  250.