/wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php

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