| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * REST API: WP_REST_Taxonomies_Controller class 4 * 5 * @package WordPress 6 * @subpackage REST_API 7 * @since 4.7.0 8 */ 9 10 /** 11 * Core class used to manage taxonomies via the REST API. 12 * 13 * @since 4.7.0 14 * 15 * @see WP_REST_Controller 16 */ 17 class WP_REST_Taxonomies_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 = 'taxonomies'; 27 } 28 29 /** 30 * Registers the routes for taxonomies. 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<taxonomy>[\w-]+)', 55 array( 56 'args' => array( 57 'taxonomy' => array( 58 'description' => __( 'An alphanumeric identifier for the taxonomy.' ), 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 taxonomies. 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 if ( ! empty( $request['type'] ) ) { 86 $taxonomies = get_object_taxonomies( $request['type'], 'objects' ); 87 } else { 88 $taxonomies = get_taxonomies( '', 'objects' ); 89 } 90 91 foreach ( $taxonomies as $taxonomy ) { 92 if ( ! empty( $taxonomy->show_in_rest ) && current_user_can( $taxonomy->cap->assign_terms ) ) { 93 return true; 94 } 95 } 96 97 return new WP_Error( 98 'rest_cannot_view', 99 __( 'Sorry, you are not allowed to manage terms in this taxonomy.' ), 100 array( 'status' => rest_authorization_required_code() ) 101 ); 102 } 103 104 return true; 105 } 106 107 /** 108 * Retrieves all public taxonomies. 109 * 110 * @since 4.7.0 111 * 112 * @param WP_REST_Request $request Full details about the request. 113 * @return WP_REST_Response Response object on success, or WP_Error object on failure. 114 */ 115 public function get_items( $request ) { 116 117 // Retrieve the list of registered collection query parameters. 118 $registered = $this->get_collection_params(); 119 120 if ( isset( $registered['type'] ) && ! empty( $request['type'] ) ) { 121 $taxonomies = get_object_taxonomies( $request['type'], 'objects' ); 122 } else { 123 $taxonomies = get_taxonomies( '', 'objects' ); 124 } 125 126 $data = array(); 127 128 foreach ( $taxonomies as $tax_type => $value ) { 129 if ( empty( $value->show_in_rest ) || ( 'edit' === $request['context'] && ! current_user_can( $value->cap->assign_terms ) ) ) { 130 continue; 131 } 132 133 $tax = $this->prepare_item_for_response( $value, $request ); 134 $tax = $this->prepare_response_for_collection( $tax ); 135 $data[ $tax_type ] = $tax; 136 } 137 138 if ( empty( $data ) ) { 139 // Response should still be returned as a JSON object when it is empty. 140 $data = (object) $data; 141 } 142 143 return rest_ensure_response( $data ); 144 } 145 146 /** 147 * Checks if a given request has access to a taxonomy. 148 * 149 * @since 4.7.0 150 * 151 * @param WP_REST_Request $request Full details about the request. 152 * @return true|WP_Error True if the request has read access for the item, otherwise false or WP_Error object. 153 */ 154 public function get_item_permissions_check( $request ) { 155 156 $tax_obj = get_taxonomy( $request['taxonomy'] ); 157 158 if ( $tax_obj ) { 159 if ( empty( $tax_obj->show_in_rest ) ) { 160 return false; 161 } 162 163 if ( 'edit' === $request['context'] && ! current_user_can( $tax_obj->cap->assign_terms ) ) { 164 return new WP_Error( 165 'rest_forbidden_context', 166 __( 'Sorry, you are not allowed to manage terms in this taxonomy.' ), 167 array( 'status' => rest_authorization_required_code() ) 168 ); 169 } 170 } 171 172 return true; 173 } 174 175 /** 176 * Retrieves a specific taxonomy. 177 * 178 * @since 4.7.0 179 * 180 * @param WP_REST_Request $request Full details about the request. 181 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. 182 */ 183 public function get_item( $request ) { 184 $tax_obj = get_taxonomy( $request['taxonomy'] ); 185 186 if ( empty( $tax_obj ) ) { 187 return new WP_Error( 188 'rest_taxonomy_invalid', 189 __( 'Invalid taxonomy.' ), 190 array( 'status' => 404 ) 191 ); 192 } 193 194 $data = $this->prepare_item_for_response( $tax_obj, $request ); 195 196 return rest_ensure_response( $data ); 197 } 198 199 /** 200 * Prepares a taxonomy object for serialization. 201 * 202 * @since 4.7.0 203 * @since 5.9.0 Renamed `$taxonomy` to `$item` to match parent class for PHP 8 named parameter support. 204 * 205 * @param WP_Taxonomy $item Taxonomy data. 206 * @param WP_REST_Request $request Full details about the request. 207 * @return WP_REST_Response Response object. 208 */ 209 public function prepare_item_for_response( $item, $request ) { 210 // Restores the more descriptive, specific name for use within this method. 211 $taxonomy = $item; 212 $base = ! empty( $taxonomy->rest_base ) ? $taxonomy->rest_base : $taxonomy->name; 213 214 $fields = $this->get_fields_for_response( $request ); 215 $data = array(); 216 217 if ( in_array( 'name', $fields, true ) ) { 218 $data['name'] = $taxonomy->label; 219 } 220 221 if ( in_array( 'slug', $fields, true ) ) { 222 $data['slug'] = $taxonomy->name; 223 } 224 225 if ( in_array( 'capabilities', $fields, true ) ) { 226 $data['capabilities'] = $taxonomy->cap; 227 } 228 229 if ( in_array( 'description', $fields, true ) ) { 230 $data['description'] = $taxonomy->description; 231 } 232 233 if ( in_array( 'labels', $fields, true ) ) { 234 $data['labels'] = $taxonomy->labels; 235 } 236 237 if ( in_array( 'types', $fields, true ) ) { 238 $data['types'] = array_values( $taxonomy->object_type ); 239 } 240 241 if ( in_array( 'show_cloud', $fields, true ) ) { 242 $data['show_cloud'] = $taxonomy->show_tagcloud; 243 } 244 245 if ( in_array( 'hierarchical', $fields, true ) ) { 246 $data['hierarchical'] = $taxonomy->hierarchical; 247 } 248 249 if ( in_array( 'rest_base', $fields, true ) ) { 250 $data['rest_base'] = $base; 251 } 252 253 if ( in_array( 'rest_namespace', $fields, true ) ) { 254 $data['rest_namespace'] = $taxonomy->rest_namespace; 255 } 256 257 if ( in_array( 'visibility', $fields, true ) ) { 258 $data['visibility'] = array( 259 'public' => (bool) $taxonomy->public, 260 'publicly_queryable' => (bool) $taxonomy->publicly_queryable, 261 'show_admin_column' => (bool) $taxonomy->show_admin_column, 262 'show_in_nav_menus' => (bool) $taxonomy->show_in_nav_menus, 263 'show_in_quick_edit' => (bool) $taxonomy->show_in_quick_edit, 264 'show_ui' => (bool) $taxonomy->show_ui, 265 ); 266 } 267 268 $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; 269 $data = $this->add_additional_fields_to_object( $data, $request ); 270 $data = $this->filter_response_by_context( $data, $context ); 271 272 // Wrap the data in a response object. 273 $response = rest_ensure_response( $data ); 274 275 $response->add_links( 276 array( 277 'collection' => array( 278 'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ), 279 ), 280 'https://api.w.org/items' => array( 281 'href' => rest_url( rest_get_route_for_taxonomy_items( $taxonomy->name ) ), 282 ), 283 ) 284 ); 285 286 /** 287 * Filters a taxonomy returned from the REST API. 288 * 289 * Allows modification of the taxonomy data right before it is returned. 290 * 291 * @since 4.7.0 292 * 293 * @param WP_REST_Response $response The response object. 294 * @param WP_Taxonomy $item The original taxonomy object. 295 * @param WP_REST_Request $request Request used to generate the response. 296 */ 297 return apply_filters( 'rest_prepare_taxonomy', $response, $taxonomy, $request ); 298 } 299 300 /** 301 * Retrieves the taxonomy's schema, conforming to JSON Schema. 302 * 303 * @since 4.7.0 304 * @since 5.0.0 The `visibility` property was added. 305 * @since 5.9.0 The `rest_namespace` property was added. 306 * 307 * @return array Item schema data. 308 */ 309 public function get_item_schema() { 310 if ( $this->schema ) { 311 return $this->add_additional_fields_schema( $this->schema ); 312 } 313 314 $schema = array( 315 '$schema' => 'http://json-schema.org/draft-04/schema#', 316 'title' => 'taxonomy', 317 'type' => 'object', 318 'properties' => array( 319 'capabilities' => array( 320 'description' => __( 'All capabilities used by the taxonomy.' ), 321 'type' => 'object', 322 'context' => array( 'edit' ), 323 'readonly' => true, 324 ), 325 'description' => array( 326 'description' => __( 'A human-readable description of the taxonomy.' ), 327 'type' => 'string', 328 'context' => array( 'view', 'edit' ), 329 'readonly' => true, 330 ), 331 'hierarchical' => array( 332 'description' => __( 'Whether or not the taxonomy should have children.' ), 333 'type' => 'boolean', 334 'context' => array( 'view', 'edit' ), 335 'readonly' => true, 336 ), 337 'labels' => array( 338 'description' => __( 'Human-readable labels for the taxonomy for various contexts.' ), 339 'type' => 'object', 340 'context' => array( 'edit' ), 341 'readonly' => true, 342 ), 343 'name' => array( 344 'description' => __( 'The title for the taxonomy.' ), 345 'type' => 'string', 346 'context' => array( 'view', 'edit', 'embed' ), 347 'readonly' => true, 348 ), 349 'slug' => array( 350 'description' => __( 'An alphanumeric identifier for the taxonomy.' ), 351 'type' => 'string', 352 'context' => array( 'view', 'edit', 'embed' ), 353 'readonly' => true, 354 ), 355 'show_cloud' => array( 356 'description' => __( 'Whether or not the term cloud should be displayed.' ), 357 'type' => 'boolean', 358 'context' => array( 'edit' ), 359 'readonly' => true, 360 ), 361 'types' => array( 362 'description' => __( 'Types associated with the taxonomy.' ), 363 'type' => 'array', 364 'items' => array( 365 'type' => 'string', 366 ), 367 'context' => array( 'view', 'edit' ), 368 'readonly' => true, 369 ), 370 'rest_base' => array( 371 'description' => __( 'REST base route for the taxonomy.' ), 372 'type' => 'string', 373 'context' => array( 'view', 'edit', 'embed' ), 374 'readonly' => true, 375 ), 376 'rest_namespace' => array( 377 'description' => __( 'REST namespace route for the taxonomy.' ), 378 'type' => 'string', 379 'context' => array( 'view', 'edit', 'embed' ), 380 'readonly' => true, 381 ), 382 'visibility' => array( 383 'description' => __( 'The visibility settings for the taxonomy.' ), 384 'type' => 'object', 385 'context' => array( 'edit' ), 386 'readonly' => true, 387 'properties' => array( 388 'public' => array( 389 'description' => __( 'Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users.' ), 390 'type' => 'boolean', 391 ), 392 'publicly_queryable' => array( 393 'description' => __( 'Whether the taxonomy is publicly queryable.' ), 394 'type' => 'boolean', 395 ), 396 'show_ui' => array( 397 'description' => __( 'Whether to generate a default UI for managing this taxonomy.' ), 398 'type' => 'boolean', 399 ), 400 'show_admin_column' => array( 401 'description' => __( 'Whether to allow automatic creation of taxonomy columns on associated post-types table.' ), 402 'type' => 'boolean', 403 ), 404 'show_in_nav_menus' => array( 405 'description' => __( 'Whether to make the taxonomy available for selection in navigation menus.' ), 406 'type' => 'boolean', 407 ), 408 'show_in_quick_edit' => array( 409 'description' => __( 'Whether to show the taxonomy in the quick/bulk edit panel.' ), 410 'type' => 'boolean', 411 ), 412 413 ), 414 ), 415 ), 416 ); 417 418 $this->schema = $schema; 419 420 return $this->add_additional_fields_schema( $this->schema ); 421 } 422 423 /** 424 * Retrieves the query params for collections. 425 * 426 * @since 4.7.0 427 * 428 * @return array Collection parameters. 429 */ 430 public function get_collection_params() { 431 $new_params = array(); 432 $new_params['context'] = $this->get_context_param( array( 'default' => 'view' ) ); 433 $new_params['type'] = array( 434 'description' => __( 'Limit results to taxonomies associated with a specific post type.' ), 435 'type' => 'string', 436 ); 437 return $new_params; 438 } 439 440 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Sat Jul 12 01:00:03 2025 | Cross-referenced by PHPXref 0.7.1 |