WP_REST_Taxonomies_Controller

Core class used to manage taxonomies via the REST API.

Defined (1)

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

/wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php  
  1. class WP_REST_Taxonomies_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 = 'taxonomies'; 
  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<taxonomy>[\w-]+)', array( 
  31. 'args' => array( 
  32. 'taxonomy' => array( 
  33. 'description' => __( 'An alphanumeric identifier for the taxonomy.' ),  
  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 taxonomies. 
  50. * @since 4.7.0 
  51. * @access public 
  52. * @param WP_REST_Request $request Full details about the request. 
  53. * @return true|WP_Error 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. if ( ! empty( $request['type'] ) ) { 
  58. $taxonomies = get_object_taxonomies( $request['type'], 'objects' ); 
  59. } else { 
  60. $taxonomies = get_taxonomies( '', 'objects' ); 
  61. foreach ( $taxonomies as $taxonomy ) { 
  62. if ( ! empty( $taxonomy->show_in_rest ) && current_user_can( $taxonomy->cap->manage_terms ) ) { 
  63. return true; 
  64. return new WP_Error( 'rest_cannot_view', __( 'Sorry, you are not allowed to manage terms in this taxonomy.' ), array( 'status' => rest_authorization_required_code() ) ); 
  65. return true; 
  66.  
  67. /** 
  68. * Retrieves all public taxonomies. 
  69. * @since 4.7.0 
  70. * @access public 
  71. * @param WP_REST_Request $request Full details about the request. 
  72. * @return WP_REST_Response Response object on success, or WP_Error object on failure. 
  73. */ 
  74. public function get_items( $request ) { 
  75.  
  76. // Retrieve the list of registered collection query parameters. 
  77. $registered = $this->get_collection_params(); 
  78.  
  79. if ( isset( $registered['type'] ) && ! empty( $request['type'] ) ) { 
  80. $taxonomies = get_object_taxonomies( $request['type'], 'objects' ); 
  81. } else { 
  82. $taxonomies = get_taxonomies( '', 'objects' ); 
  83. $data = array(); 
  84. foreach ( $taxonomies as $tax_type => $value ) { 
  85. if ( empty( $value->show_in_rest ) || ( 'edit' === $request['context'] && ! current_user_can( $value->cap->manage_terms ) ) ) { 
  86. continue; 
  87. $tax = $this->prepare_item_for_response( $value, $request ); 
  88. $tax = $this->prepare_response_for_collection( $tax ); 
  89. $data[ $tax_type ] = $tax; 
  90.  
  91. if ( empty( $data ) ) { 
  92. // Response should still be returned as a JSON object when it is empty. 
  93. $data = (object) $data; 
  94.  
  95. return rest_ensure_response( $data ); 
  96.  
  97. /** 
  98. * Checks if a given request has access to a taxonomy. 
  99. * @since 4.7.0 
  100. * @access public 
  101. * @param WP_REST_Request $request Full details about the request. 
  102. * @return true|WP_Error True if the request has read access for the item, otherwise false or WP_Error object. 
  103. */ 
  104. public function get_item_permissions_check( $request ) { 
  105.  
  106. $tax_obj = get_taxonomy( $request['taxonomy'] ); 
  107.  
  108. if ( $tax_obj ) { 
  109. if ( empty( $tax_obj->show_in_rest ) ) { 
  110. return false; 
  111. if ( 'edit' === $request['context'] && ! current_user_can( $tax_obj->cap->manage_terms ) ) { 
  112. return new WP_Error( 'rest_forbidden_context', __( 'Sorry, you are not allowed to manage terms in this taxonomy.' ), array( 'status' => rest_authorization_required_code() ) ); 
  113.  
  114. return true; 
  115.  
  116. /** 
  117. * Retrieves a specific taxonomy. 
  118. * @since 4.7.0 
  119. * @access public 
  120. * @param WP_REST_Request $request Full details about the request. 
  121. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 
  122. */ 
  123. public function get_item( $request ) { 
  124. $tax_obj = get_taxonomy( $request['taxonomy'] ); 
  125. if ( empty( $tax_obj ) ) { 
  126. return new WP_Error( 'rest_taxonomy_invalid', __( 'Invalid taxonomy.' ), array( 'status' => 404 ) ); 
  127. $data = $this->prepare_item_for_response( $tax_obj, $request ); 
  128. return rest_ensure_response( $data ); 
  129.  
  130. /** 
  131. * Prepares a taxonomy object for serialization. 
  132. * @since 4.7.0 
  133. * @access public 
  134. * @param stdClass $taxonomy Taxonomy data. 
  135. * @param WP_REST_Request $request Full details about the request. 
  136. * @return WP_REST_Response Response object. 
  137. */ 
  138. public function prepare_item_for_response( $taxonomy, $request ) { 
  139. $base = ! empty( $taxonomy->rest_base ) ? $taxonomy->rest_base : $taxonomy->name; 
  140. $data = array( 
  141. 'name' => $taxonomy->label,  
  142. 'slug' => $taxonomy->name,  
  143. 'capabilities' => $taxonomy->cap,  
  144. 'description' => $taxonomy->description,  
  145. 'labels' => $taxonomy->labels,  
  146. 'types' => $taxonomy->object_type,  
  147. 'show_cloud' => $taxonomy->show_tagcloud,  
  148. 'hierarchical' => $taxonomy->hierarchical,  
  149. 'rest_base' => $base,  
  150. ); 
  151.  
  152. $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; 
  153. $data = $this->add_additional_fields_to_object( $data, $request ); 
  154. $data = $this->filter_response_by_context( $data, $context ); 
  155.  
  156. // Wrap the data in a response object. 
  157. $response = rest_ensure_response( $data ); 
  158.  
  159. $response->add_links( array( 
  160. 'collection' => array( 
  161. 'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),  
  162. ),  
  163. 'https://api.w.org/items' => array( 
  164. 'href' => rest_url( sprintf( 'wp/v2/%s', $base ) ),  
  165. ),  
  166. ) ); 
  167.  
  168. /** 
  169. * Filters a taxonomy returned from the REST API. 
  170. * Allows modification of the taxonomy data right before it is returned. 
  171. * @since 4.7.0 
  172. * @param WP_REST_Response $response The response object. 
  173. * @param object $item The original taxonomy object. 
  174. * @param WP_REST_Request $request Request used to generate the response. 
  175. */ 
  176. return apply_filters( 'rest_prepare_taxonomy', $response, $taxonomy, $request ); 
  177.  
  178. /** 
  179. * Retrieves the taxonomy's schema, conforming to JSON Schema. 
  180. * @since 4.7.0 
  181. * @access public 
  182. * @return array Item schema data. 
  183. */ 
  184. public function get_item_schema() { 
  185. $schema = array( 
  186. '$schema' => 'http://json-schema.org/schema#',  
  187. 'title' => 'taxonomy',  
  188. 'type' => 'object',  
  189. 'properties' => array( 
  190. 'capabilities' => array( 
  191. 'description' => __( 'All capabilities used by the taxonomy.' ),  
  192. 'type' => 'object',  
  193. 'context' => array( 'edit' ),  
  194. 'readonly' => true,  
  195. ),  
  196. 'description' => array( 
  197. 'description' => __( 'A human-readable description of the taxonomy.' ),  
  198. 'type' => 'string',  
  199. 'context' => array( 'view', 'edit' ),  
  200. 'readonly' => true,  
  201. ),  
  202. 'hierarchical' => array( 
  203. 'description' => __( 'Whether or not the taxonomy should have children.' ),  
  204. 'type' => 'boolean',  
  205. 'context' => array( 'view', 'edit' ),  
  206. 'readonly' => true,  
  207. ),  
  208. 'labels' => array( 
  209. 'description' => __( 'Human-readable labels for the taxonomy for various contexts.' ),  
  210. 'type' => 'object',  
  211. 'context' => array( 'edit' ),  
  212. 'readonly' => true,  
  213. ),  
  214. 'name' => array( 
  215. 'description' => __( 'The title for the taxonomy.' ),  
  216. 'type' => 'string',  
  217. 'context' => array( 'view', 'edit', 'embed' ),  
  218. 'readonly' => true,  
  219. ),  
  220. 'slug' => array( 
  221. 'description' => __( 'An alphanumeric identifier for the taxonomy.' ),  
  222. 'type' => 'string',  
  223. 'context' => array( 'view', 'edit', 'embed' ),  
  224. 'readonly' => true,  
  225. ),  
  226. 'show_cloud' => array( 
  227. 'description' => __( 'Whether or not the term cloud should be displayed.' ),  
  228. 'type' => 'boolean',  
  229. 'context' => array( 'edit' ),  
  230. 'readonly' => true,  
  231. ),  
  232. 'types' => array( 
  233. 'description' => __( 'Types associated with the taxonomy.' ),  
  234. 'type' => 'array',  
  235. 'items' => array( 
  236. 'type' => 'string',  
  237. ),  
  238. 'context' => array( 'view', 'edit' ),  
  239. 'readonly' => true,  
  240. ),  
  241. 'rest_base' => array( 
  242. 'description' => __( 'REST base route for the taxonomy.' ),  
  243. 'type' => 'string',  
  244. 'context' => array( 'view', 'edit', 'embed' ),  
  245. 'readonly' => true,  
  246. ),  
  247. ),  
  248. ); 
  249. return $this->add_additional_fields_schema( $schema ); 
  250.  
  251. /** 
  252. * Retrieves the query params for collections. 
  253. * @since 4.7.0 
  254. * @access public 
  255. * @return array Collection parameters. 
  256. */ 
  257. public function get_collection_params() { 
  258. $new_params = array(); 
  259. $new_params['context'] = $this->get_context_param( array( 'default' => 'view' ) ); 
  260. $new_params['type'] = array( 
  261. 'description' => __( 'Limit results to taxonomies associated with a specific post type.' ),  
  262. 'type' => 'string',  
  263. ); 
  264. return $new_params; 
  265.