| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Taxonomy API: WP_Taxonomy class 4 * 5 * @package WordPress 6 * @subpackage Taxonomy 7 * @since 4.7.0 8 */ 9 10 /** 11 * Core class used for interacting with taxonomies. 12 * 13 * @since 4.7.0 14 */ 15 #[AllowDynamicProperties] 16 final class WP_Taxonomy { 17 /** 18 * Taxonomy key. 19 * 20 * @since 4.7.0 21 * @var string 22 */ 23 public $name; 24 25 /** 26 * Name of the taxonomy shown in the menu. Usually plural. 27 * 28 * @since 4.7.0 29 * @var string 30 */ 31 public $label; 32 33 /** 34 * Labels object for this taxonomy. 35 * 36 * If not set, tag labels are inherited for non-hierarchical types 37 * and category labels for hierarchical ones. 38 * 39 * @see get_taxonomy_labels() 40 * 41 * @since 4.7.0 42 * @var stdClass 43 */ 44 public $labels; 45 46 /** 47 * Default labels. 48 * 49 * @since 6.0.0 50 * @var (string|null)[][] $default_labels 51 */ 52 protected static $default_labels = array(); 53 54 /** 55 * A short descriptive summary of what the taxonomy is for. 56 * 57 * @since 4.7.0 58 * @var string 59 */ 60 public $description = ''; 61 62 /** 63 * Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users. 64 * 65 * @since 4.7.0 66 * @var bool 67 */ 68 public $public = true; 69 70 /** 71 * Whether the taxonomy is publicly queryable. 72 * 73 * @since 4.7.0 74 * @var bool 75 */ 76 public $publicly_queryable = true; 77 78 /** 79 * Whether the taxonomy is hierarchical. 80 * 81 * @since 4.7.0 82 * @var bool 83 */ 84 public $hierarchical = false; 85 86 /** 87 * Whether to generate and allow a UI for managing terms in this taxonomy in the admin. 88 * 89 * @since 4.7.0 90 * @var bool 91 */ 92 public $show_ui = true; 93 94 /** 95 * Whether to show the taxonomy in the admin menu. 96 * 97 * If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown. 98 * 99 * @since 4.7.0 100 * @var bool 101 */ 102 public $show_in_menu = true; 103 104 /** 105 * Whether the taxonomy is available for selection in navigation menus. 106 * 107 * @since 4.7.0 108 * @var bool 109 */ 110 public $show_in_nav_menus = true; 111 112 /** 113 * Whether to list the taxonomy in the tag cloud widget controls. 114 * 115 * @since 4.7.0 116 * @var bool 117 */ 118 public $show_tagcloud = true; 119 120 /** 121 * Whether to show the taxonomy in the quick/bulk edit panel. 122 * 123 * @since 4.7.0 124 * @var bool 125 */ 126 public $show_in_quick_edit = true; 127 128 /** 129 * Whether to display a column for the taxonomy on its post type listing screens. 130 * 131 * @since 4.7.0 132 * @var bool 133 */ 134 public $show_admin_column = false; 135 136 /** 137 * The callback function for the meta box display. 138 * 139 * @since 4.7.0 140 * @var bool|callable 141 */ 142 public $meta_box_cb = null; 143 144 /** 145 * The callback function for sanitizing taxonomy data saved from a meta box. 146 * 147 * @since 5.1.0 148 * @var callable 149 */ 150 public $meta_box_sanitize_cb = null; 151 152 /** 153 * An array of object types this taxonomy is registered for. 154 * 155 * @since 4.7.0 156 * @var string[] 157 */ 158 public $object_type = null; 159 160 /** 161 * Capabilities for this taxonomy. 162 * 163 * @see register_taxonomy() 164 * 165 * @since 4.7.0 166 * @var stdClass { 167 * Object with all the capabilities as member variables. 168 * 169 * @type string $manage_terms Capability to manage terms. Default 'manage_categories'. 170 * @type string $edit_terms Capability to edit terms. Default 'manage_categories'. 171 * @type string $delete_terms Capability to delete terms. Default 'manage_categories'. 172 * @type string $assign_terms Capability to assign terms. Default 'edit_posts'. 173 * } 174 */ 175 public $cap; 176 177 /** 178 * Rewrites information for this taxonomy. 179 * 180 * @since 4.7.0 181 * @var array|false 182 */ 183 public $rewrite; 184 185 /** 186 * Query var string for this taxonomy. 187 * 188 * @since 4.7.0 189 * @var string|false 190 */ 191 public $query_var; 192 193 /** 194 * Function that will be called when the count is updated. 195 * 196 * @since 4.7.0 197 * @var callable 198 */ 199 public $update_count_callback; 200 201 /** 202 * Whether this taxonomy should appear in the REST API. 203 * 204 * Default false. If true, standard endpoints will be registered with 205 * respect to $rest_base and $rest_controller_class. 206 * 207 * @since 4.7.4 208 * @var bool $show_in_rest 209 */ 210 public $show_in_rest; 211 212 /** 213 * The base path for this taxonomy's REST API endpoints. 214 * 215 * @since 4.7.4 216 * @var string|bool $rest_base 217 */ 218 public $rest_base; 219 220 /** 221 * The namespace for this taxonomy's REST API endpoints. 222 * 223 * @since 5.9.0 224 * @var string|bool $rest_namespace 225 */ 226 public $rest_namespace; 227 228 /** 229 * The controller for this taxonomy's REST API endpoints. 230 * 231 * Custom controllers must extend WP_REST_Controller. 232 * 233 * @since 4.7.4 234 * @var string|bool $rest_controller_class 235 */ 236 public $rest_controller_class; 237 238 /** 239 * The controller instance for this taxonomy's REST API endpoints. 240 * 241 * Lazily computed. Should be accessed using {@see WP_Taxonomy::get_rest_controller()}. 242 * 243 * @since 5.5.0 244 * @var WP_REST_Controller $rest_controller 245 */ 246 public $rest_controller; 247 248 /** 249 * The default term name for this taxonomy. If you pass an array you have 250 * to set 'name' and optionally 'slug' and 'description'. 251 * 252 * @since 5.5.0 253 * @var array|string 254 */ 255 public $default_term; 256 257 /** 258 * Whether terms in this taxonomy should be sorted in the order they are provided to `wp_set_object_terms()`. 259 * 260 * Use this in combination with `'orderby' => 'term_order'` when fetching terms. 261 * 262 * @since 2.5.0 263 * @var bool|null 264 */ 265 public $sort = null; 266 267 /** 268 * Array of arguments to automatically use inside `wp_get_object_terms()` for this taxonomy. 269 * 270 * @since 2.6.0 271 * @var array|null 272 */ 273 public $args = null; 274 275 /** 276 * Whether it is a built-in taxonomy. 277 * 278 * @since 4.7.0 279 * @var bool 280 */ 281 public $_builtin; 282 283 /** 284 * Constructor. 285 * 286 * See the register_taxonomy() function for accepted arguments for `$args`. 287 * 288 * @since 4.7.0 289 * 290 * @param string $taxonomy Taxonomy key, must not exceed 32 characters. 291 * @param array|string $object_type Name of the object type for the taxonomy object. 292 * @param array|string $args Optional. Array or query string of arguments for registering a taxonomy. 293 * See register_taxonomy() for information on accepted arguments. 294 * Default empty array. 295 */ 296 public function __construct( $taxonomy, $object_type, $args = array() ) { 297 $this->name = $taxonomy; 298 299 $this->set_props( $object_type, $args ); 300 } 301 302 /** 303 * Sets taxonomy properties. 304 * 305 * See the register_taxonomy() function for accepted arguments for `$args`. 306 * 307 * @since 4.7.0 308 * 309 * @param string|string[] $object_type Name or array of names of the object types for the taxonomy. 310 * @param array|string $args Array or query string of arguments for registering a taxonomy. 311 */ 312 public function set_props( $object_type, $args ) { 313 $args = wp_parse_args( $args ); 314 315 /** 316 * Filters the arguments for registering a taxonomy. 317 * 318 * @since 4.4.0 319 * 320 * @param array $args Array of arguments for registering a taxonomy. 321 * See the register_taxonomy() function for accepted arguments. 322 * @param string $taxonomy Taxonomy key. 323 * @param string[] $object_type Array of names of object types for the taxonomy. 324 */ 325 $args = apply_filters( 'register_taxonomy_args', $args, $this->name, (array) $object_type ); 326 327 $taxonomy = $this->name; 328 329 /** 330 * Filters the arguments for registering a specific taxonomy. 331 * 332 * The dynamic portion of the filter name, `$taxonomy`, refers to the taxonomy key. 333 * 334 * Possible hook names include: 335 * 336 * - `register_category_taxonomy_args` 337 * - `register_post_tag_taxonomy_args` 338 * 339 * @since 6.0.0 340 * 341 * @param array $args Array of arguments for registering a taxonomy. 342 * See the register_taxonomy() function for accepted arguments. 343 * @param string $taxonomy Taxonomy key. 344 * @param string[] $object_type Array of names of object types for the taxonomy. 345 */ 346 $args = apply_filters( "register_{$taxonomy}_taxonomy_args", $args, $this->name, (array) $object_type ); 347 348 $defaults = array( 349 'labels' => array(), 350 'description' => '', 351 'public' => true, 352 'publicly_queryable' => null, 353 'hierarchical' => false, 354 'show_ui' => null, 355 'show_in_menu' => null, 356 'show_in_nav_menus' => null, 357 'show_tagcloud' => null, 358 'show_in_quick_edit' => null, 359 'show_admin_column' => false, 360 'meta_box_cb' => null, 361 'meta_box_sanitize_cb' => null, 362 'capabilities' => array(), 363 'rewrite' => true, 364 'query_var' => $this->name, 365 'update_count_callback' => '', 366 'show_in_rest' => false, 367 'rest_base' => false, 368 'rest_namespace' => false, 369 'rest_controller_class' => false, 370 'default_term' => null, 371 'sort' => null, 372 'args' => null, 373 '_builtin' => false, 374 ); 375 376 $args = array_merge( $defaults, $args ); 377 378 // If not set, default to the setting for 'public'. 379 $args['publicly_queryable'] ??= $args['public']; 380 381 if ( false !== $args['query_var'] && ( is_admin() || false !== $args['publicly_queryable'] ) ) { 382 if ( true === $args['query_var'] ) { 383 $args['query_var'] = $this->name; 384 } else { 385 $args['query_var'] = sanitize_title_with_dashes( $args['query_var'] ); 386 } 387 } else { 388 // Force 'query_var' to false for non-public taxonomies. 389 $args['query_var'] = false; 390 } 391 392 if ( false !== $args['rewrite'] && ( is_admin() || get_option( 'permalink_structure' ) ) ) { 393 $args['rewrite'] = wp_parse_args( 394 $args['rewrite'], 395 array( 396 'with_front' => true, 397 'hierarchical' => false, 398 'ep_mask' => EP_NONE, 399 ) 400 ); 401 402 if ( empty( $args['rewrite']['slug'] ) ) { 403 $args['rewrite']['slug'] = sanitize_title_with_dashes( $this->name ); 404 } 405 } 406 407 // If not set, default to the setting for 'public'. 408 $args['show_ui'] ??= $args['public']; 409 410 // If not set, default to the setting for 'show_ui'. 411 if ( null === $args['show_in_menu'] || ! $args['show_ui'] ) { 412 $args['show_in_menu'] = $args['show_ui']; 413 } 414 415 // If not set, default to the setting for 'public'. 416 $args['show_in_nav_menus'] ??= $args['public']; 417 418 // If not set, default to the setting for 'show_ui'. 419 $args['show_tagcloud'] ??= $args['show_ui']; 420 421 // If not set, default to the setting for 'show_ui'. 422 $args['show_in_quick_edit'] ??= $args['show_ui']; 423 424 // If not set, default rest_namespace to wp/v2 if show_in_rest is true. 425 if ( false === $args['rest_namespace'] && ! empty( $args['show_in_rest'] ) ) { 426 $args['rest_namespace'] = 'wp/v2'; 427 } 428 429 $default_caps = array( 430 'manage_terms' => 'manage_categories', 431 'edit_terms' => 'manage_categories', 432 'delete_terms' => 'manage_categories', 433 'assign_terms' => 'edit_posts', 434 ); 435 436 $args['cap'] = (object) array_merge( $default_caps, $args['capabilities'] ); 437 unset( $args['capabilities'] ); 438 439 $args['object_type'] = array_unique( (array) $object_type ); 440 441 // If not set, use the default meta box. 442 if ( null === $args['meta_box_cb'] ) { 443 if ( $args['hierarchical'] ) { 444 $args['meta_box_cb'] = 'post_categories_meta_box'; 445 } else { 446 $args['meta_box_cb'] = 'post_tags_meta_box'; 447 } 448 } 449 450 $args['name'] = $this->name; 451 452 // Default meta box sanitization callback depends on the value of 'meta_box_cb'. 453 if ( null === $args['meta_box_sanitize_cb'] ) { 454 switch ( $args['meta_box_cb'] ) { 455 case 'post_categories_meta_box': 456 $args['meta_box_sanitize_cb'] = 'taxonomy_meta_box_sanitize_cb_checkboxes'; 457 break; 458 459 case 'post_tags_meta_box': 460 default: 461 $args['meta_box_sanitize_cb'] = 'taxonomy_meta_box_sanitize_cb_input'; 462 break; 463 } 464 } 465 466 // Default taxonomy term. 467 if ( ! empty( $args['default_term'] ) ) { 468 if ( ! is_array( $args['default_term'] ) ) { 469 $args['default_term'] = array( 'name' => $args['default_term'] ); 470 } 471 $args['default_term'] = wp_parse_args( 472 $args['default_term'], 473 array( 474 'name' => '', 475 'slug' => '', 476 'description' => '', 477 ) 478 ); 479 } 480 481 foreach ( $args as $property_name => $property_value ) { 482 $this->$property_name = $property_value; 483 } 484 485 $this->labels = get_taxonomy_labels( $this ); 486 $this->label = $this->labels->name; 487 } 488 489 /** 490 * Adds the necessary rewrite rules for the taxonomy. 491 * 492 * @since 4.7.0 493 * 494 * @global WP $wp Current WordPress environment instance. 495 */ 496 public function add_rewrite_rules() { 497 /* @var WP $wp */ 498 global $wp; 499 500 // Non-publicly queryable taxonomies should not register query vars, except in the admin. 501 if ( false !== $this->query_var && $wp ) { 502 $wp->add_query_var( $this->query_var ); 503 } 504 505 if ( false !== $this->rewrite && ( is_admin() || get_option( 'permalink_structure' ) ) ) { 506 if ( $this->hierarchical && $this->rewrite['hierarchical'] ) { 507 $tag = '(.+?)'; 508 } else { 509 $tag = '([^/]+)'; 510 } 511 512 add_rewrite_tag( "%$this->name%", $tag, $this->query_var ? "{$this->query_var}=" : "taxonomy=$this->name&term=" ); 513 add_permastruct( $this->name, "{$this->rewrite['slug']}/%$this->name%", $this->rewrite ); 514 } 515 } 516 517 /** 518 * Removes any rewrite rules, permastructs, and rules for the taxonomy. 519 * 520 * @since 4.7.0 521 * 522 * @global WP $wp Current WordPress environment instance. 523 */ 524 public function remove_rewrite_rules() { 525 /* @var WP $wp */ 526 global $wp; 527 528 // Remove query var. 529 if ( false !== $this->query_var ) { 530 $wp->remove_query_var( $this->query_var ); 531 } 532 533 // Remove rewrite tags and permastructs. 534 if ( false !== $this->rewrite ) { 535 remove_rewrite_tag( "%$this->name%" ); 536 remove_permastruct( $this->name ); 537 } 538 } 539 540 /** 541 * Registers the ajax callback for the meta box. 542 * 543 * @since 4.7.0 544 */ 545 public function add_hooks() { 546 add_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' ); 547 } 548 549 /** 550 * Removes the ajax callback for the meta box. 551 * 552 * @since 4.7.0 553 */ 554 public function remove_hooks() { 555 remove_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' ); 556 } 557 558 /** 559 * Gets the REST API controller for this taxonomy. 560 * 561 * Will only instantiate the controller class once per request. 562 * 563 * @since 5.5.0 564 * 565 * @return WP_REST_Controller|null The controller instance, or null if the taxonomy 566 * is set not to show in rest. 567 */ 568 public function get_rest_controller() { 569 if ( ! $this->show_in_rest ) { 570 return null; 571 } 572 573 $class = $this->rest_controller_class ? $this->rest_controller_class : WP_REST_Terms_Controller::class; 574 575 if ( ! class_exists( $class ) ) { 576 return null; 577 } 578 579 if ( ! is_subclass_of( $class, WP_REST_Controller::class ) ) { 580 return null; 581 } 582 583 if ( ! $this->rest_controller ) { 584 $this->rest_controller = new $class( $this->name ); 585 } 586 587 if ( ! ( $this->rest_controller instanceof $class ) ) { 588 return null; 589 } 590 591 return $this->rest_controller; 592 } 593 594 /** 595 * Returns the default labels for taxonomies. 596 * 597 * @since 6.0.0 598 * 599 * @return (string|null)[][] The default labels for taxonomies. 600 */ 601 public static function get_default_labels() { 602 if ( ! empty( self::$default_labels ) ) { 603 return self::$default_labels; 604 } 605 606 $name_field_description = __( 'The name is how it appears on your site.' ); 607 $slug_field_description = __( 'The “slug” is the URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, and hyphens.' ); 608 $parent_field_description = __( 'Assign a parent term to create a hierarchy. The term Jazz, for example, would be the parent of Bebop and Big Band.' ); 609 $desc_field_description = __( 'The description is not prominent by default; however, some themes may show it.' ); 610 611 self::$default_labels = array( 612 'name' => array( _x( 'Tags', 'taxonomy general name' ), _x( 'Categories', 'taxonomy general name' ) ), 613 'singular_name' => array( _x( 'Tag', 'taxonomy singular name' ), _x( 'Category', 'taxonomy singular name' ) ), 614 'search_items' => array( __( 'Search Tags' ), __( 'Search Categories' ) ), 615 'popular_items' => array( __( 'Popular Tags' ), null ), 616 'all_items' => array( __( 'All Tags' ), __( 'All Categories' ) ), 617 'parent_item' => array( null, __( 'Parent Category' ) ), 618 'parent_item_colon' => array( null, __( 'Parent Category:' ) ), 619 'name_field_description' => array( $name_field_description, $name_field_description ), 620 'slug_field_description' => array( $slug_field_description, $slug_field_description ), 621 'parent_field_description' => array( null, $parent_field_description ), 622 'desc_field_description' => array( $desc_field_description, $desc_field_description ), 623 'edit_item' => array( __( 'Edit Tag' ), __( 'Edit Category' ) ), 624 'view_item' => array( __( 'View Tag' ), __( 'View Category' ) ), 625 'update_item' => array( __( 'Update Tag' ), __( 'Update Category' ) ), 626 'add_new_item' => array( __( 'Add Tag' ), __( 'Add Category' ) ), 627 'new_item_name' => array( __( 'New Tag Name' ), __( 'New Category Name' ) ), 628 'separate_items_with_commas' => array( __( 'Separate tags with commas' ), null ), 629 'add_or_remove_items' => array( __( 'Add or remove tags' ), null ), 630 'choose_from_most_used' => array( __( 'Choose from the most used tags' ), null ), 631 'not_found' => array( __( 'No tags found.' ), __( 'No categories found.' ) ), 632 'no_terms' => array( __( 'No tags' ), __( 'No categories' ) ), 633 'filter_by_item' => array( null, __( 'Filter by category' ) ), 634 'items_list_navigation' => array( __( 'Tags list navigation' ), __( 'Categories list navigation' ) ), 635 'items_list' => array( __( 'Tags list' ), __( 'Categories list' ) ), 636 /* translators: Tab heading when selecting from the most used terms. */ 637 'most_used' => array( _x( 'Most Used', 'tags' ), _x( 'Most Used', 'categories' ) ), 638 'back_to_items' => array( __( '← Go to Tags' ), __( '← Go to Categories' ) ), 639 'item_link' => array( 640 _x( 'Tag Link', 'navigation link block title' ), 641 _x( 'Category Link', 'navigation link block title' ), 642 ), 643 'item_link_description' => array( 644 _x( 'A link to a tag.', 'navigation link block description' ), 645 _x( 'A link to a category.', 'navigation link block description' ), 646 ), 647 ); 648 649 return self::$default_labels; 650 } 651 652 /** 653 * Resets the cache for the default labels. 654 * 655 * @since 6.0.0 656 */ 657 public static function reset_default_labels() { 658 self::$default_labels = array(); 659 } 660 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Tue Sep 15 08:20:32 2026 | Cross-referenced by PHPXref |