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