| [ 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 * @since 4.7.0 164 * @var stdClass 165 */ 166 public $cap; 167 168 /** 169 * Rewrites information for this taxonomy. 170 * 171 * @since 4.7.0 172 * @var array|false 173 */ 174 public $rewrite; 175 176 /** 177 * Query var string for this taxonomy. 178 * 179 * @since 4.7.0 180 * @var string|false 181 */ 182 public $query_var; 183 184 /** 185 * Function that will be called when the count is updated. 186 * 187 * @since 4.7.0 188 * @var callable 189 */ 190 public $update_count_callback; 191 192 /** 193 * Whether this taxonomy should appear in the REST API. 194 * 195 * Default false. If true, standard endpoints will be registered with 196 * respect to $rest_base and $rest_controller_class. 197 * 198 * @since 4.7.4 199 * @var bool $show_in_rest 200 */ 201 public $show_in_rest; 202 203 /** 204 * The base path for this taxonomy's REST API endpoints. 205 * 206 * @since 4.7.4 207 * @var string|bool $rest_base 208 */ 209 public $rest_base; 210 211 /** 212 * The namespace for this taxonomy's REST API endpoints. 213 * 214 * @since 5.9.0 215 * @var string|bool $rest_namespace 216 */ 217 public $rest_namespace; 218 219 /** 220 * The controller for this taxonomy's REST API endpoints. 221 * 222 * Custom controllers must extend WP_REST_Controller. 223 * 224 * @since 4.7.4 225 * @var string|bool $rest_controller_class 226 */ 227 public $rest_controller_class; 228 229 /** 230 * The controller instance for this taxonomy's REST API endpoints. 231 * 232 * Lazily computed. Should be accessed using {@see WP_Taxonomy::get_rest_controller()}. 233 * 234 * @since 5.5.0 235 * @var WP_REST_Controller $rest_controller 236 */ 237 public $rest_controller; 238 239 /** 240 * The default term name for this taxonomy. If you pass an array you have 241 * to set 'name' and optionally 'slug' and 'description'. 242 * 243 * @since 5.5.0 244 * @var array|string 245 */ 246 public $default_term; 247 248 /** 249 * Whether terms in this taxonomy should be sorted in the order they are provided to `wp_set_object_terms()`. 250 * 251 * Use this in combination with `'orderby' => 'term_order'` when fetching terms. 252 * 253 * @since 2.5.0 254 * @var bool|null 255 */ 256 public $sort = null; 257 258 /** 259 * Array of arguments to automatically use inside `wp_get_object_terms()` for this taxonomy. 260 * 261 * @since 2.6.0 262 * @var array|null 263 */ 264 public $args = null; 265 266 /** 267 * Whether it is a built-in taxonomy. 268 * 269 * @since 4.7.0 270 * @var bool 271 */ 272 public $_builtin; 273 274 /** 275 * Constructor. 276 * 277 * See the register_taxonomy() function for accepted arguments for `$args`. 278 * 279 * @since 4.7.0 280 * 281 * @param string $taxonomy Taxonomy key, must not exceed 32 characters. 282 * @param array|string $object_type Name of the object type for the taxonomy object. 283 * @param array|string $args Optional. Array or query string of arguments for registering a taxonomy. 284 * See register_taxonomy() for information on accepted arguments. 285 * Default empty array. 286 */ 287 public function __construct( $taxonomy, $object_type, $args = array() ) { 288 $this->name = $taxonomy; 289 290 $this->set_props( $object_type, $args ); 291 } 292 293 /** 294 * Sets taxonomy properties. 295 * 296 * See the register_taxonomy() function for accepted arguments for `$args`. 297 * 298 * @since 4.7.0 299 * 300 * @param string|string[] $object_type Name or array of names of the object types for the taxonomy. 301 * @param array|string $args Array or query string of arguments for registering a taxonomy. 302 */ 303 public function set_props( $object_type, $args ) { 304 $args = wp_parse_args( $args ); 305 306 /** 307 * Filters the arguments for registering a taxonomy. 308 * 309 * @since 4.4.0 310 * 311 * @param array $args Array of arguments for registering a taxonomy. 312 * See the register_taxonomy() function for accepted arguments. 313 * @param string $taxonomy Taxonomy key. 314 * @param string[] $object_type Array of names of object types for the taxonomy. 315 */ 316 $args = apply_filters( 'register_taxonomy_args', $args, $this->name, (array) $object_type ); 317 318 $taxonomy = $this->name; 319 320 /** 321 * Filters the arguments for registering a specific taxonomy. 322 * 323 * The dynamic portion of the filter name, `$taxonomy`, refers to the taxonomy key. 324 * 325 * Possible hook names include: 326 * 327 * - `register_category_taxonomy_args` 328 * - `register_post_tag_taxonomy_args` 329 * 330 * @since 6.0.0 331 * 332 * @param array $args Array of arguments for registering a taxonomy. 333 * See the register_taxonomy() function for accepted arguments. 334 * @param string $taxonomy Taxonomy key. 335 * @param string[] $object_type Array of names of object types for the taxonomy. 336 */ 337 $args = apply_filters( "register_{$taxonomy}_taxonomy_args", $args, $this->name, (array) $object_type ); 338 339 $defaults = array( 340 'labels' => array(), 341 'description' => '', 342 'public' => true, 343 'publicly_queryable' => null, 344 'hierarchical' => false, 345 'show_ui' => null, 346 'show_in_menu' => null, 347 'show_in_nav_menus' => null, 348 'show_tagcloud' => null, 349 'show_in_quick_edit' => null, 350 'show_admin_column' => false, 351 'meta_box_cb' => null, 352 'meta_box_sanitize_cb' => null, 353 'capabilities' => array(), 354 'rewrite' => true, 355 'query_var' => $this->name, 356 'update_count_callback' => '', 357 'show_in_rest' => false, 358 'rest_base' => false, 359 'rest_namespace' => false, 360 'rest_controller_class' => false, 361 'default_term' => null, 362 'sort' => null, 363 'args' => null, 364 '_builtin' => false, 365 ); 366 367 $args = array_merge( $defaults, $args ); 368 369 // If not set, default to the setting for 'public'. 370 if ( null === $args['publicly_queryable'] ) { 371 $args['publicly_queryable'] = $args['public']; 372 } 373 374 if ( false !== $args['query_var'] && ( is_admin() || false !== $args['publicly_queryable'] ) ) { 375 if ( true === $args['query_var'] ) { 376 $args['query_var'] = $this->name; 377 } else { 378 $args['query_var'] = sanitize_title_with_dashes( $args['query_var'] ); 379 } 380 } else { 381 // Force 'query_var' to false for non-public taxonomies. 382 $args['query_var'] = false; 383 } 384 385 if ( false !== $args['rewrite'] && ( is_admin() || get_option( 'permalink_structure' ) ) ) { 386 $args['rewrite'] = wp_parse_args( 387 $args['rewrite'], 388 array( 389 'with_front' => true, 390 'hierarchical' => false, 391 'ep_mask' => EP_NONE, 392 ) 393 ); 394 395 if ( empty( $args['rewrite']['slug'] ) ) { 396 $args['rewrite']['slug'] = sanitize_title_with_dashes( $this->name ); 397 } 398 } 399 400 // If not set, default to the setting for 'public'. 401 if ( null === $args['show_ui'] ) { 402 $args['show_ui'] = $args['public']; 403 } 404 405 // If not set, default to the setting for 'show_ui'. 406 if ( null === $args['show_in_menu'] || ! $args['show_ui'] ) { 407 $args['show_in_menu'] = $args['show_ui']; 408 } 409 410 // If not set, default to the setting for 'public'. 411 if ( null === $args['show_in_nav_menus'] ) { 412 $args['show_in_nav_menus'] = $args['public']; 413 } 414 415 // If not set, default to the setting for 'show_ui'. 416 if ( null === $args['show_tagcloud'] ) { 417 $args['show_tagcloud'] = $args['show_ui']; 418 } 419 420 // If not set, default to the setting for 'show_ui'. 421 if ( null === $args['show_in_quick_edit'] ) { 422 $args['show_in_quick_edit'] = $args['show_ui']; 423 } 424 425 // If not set, default rest_namespace to wp/v2 if show_in_rest is true. 426 if ( false === $args['rest_namespace'] && ! empty( $args['show_in_rest'] ) ) { 427 $args['rest_namespace'] = 'wp/v2'; 428 } 429 430 $default_caps = array( 431 'manage_terms' => 'manage_categories', 432 'edit_terms' => 'manage_categories', 433 'delete_terms' => 'manage_categories', 434 'assign_terms' => 'edit_posts', 435 ); 436 437 $args['cap'] = (object) array_merge( $default_caps, $args['capabilities'] ); 438 unset( $args['capabilities'] ); 439 440 $args['object_type'] = array_unique( (array) $object_type ); 441 442 // If not set, use the default meta box. 443 if ( null === $args['meta_box_cb'] ) { 444 if ( $args['hierarchical'] ) { 445 $args['meta_box_cb'] = 'post_categories_meta_box'; 446 } else { 447 $args['meta_box_cb'] = 'post_tags_meta_box'; 448 } 449 } 450 451 $args['name'] = $this->name; 452 453 // Default meta box sanitization callback depends on the value of 'meta_box_cb'. 454 if ( null === $args['meta_box_sanitize_cb'] ) { 455 switch ( $args['meta_box_cb'] ) { 456 case 'post_categories_meta_box': 457 $args['meta_box_sanitize_cb'] = 'taxonomy_meta_box_sanitize_cb_checkboxes'; 458 break; 459 460 case 'post_tags_meta_box': 461 default: 462 $args['meta_box_sanitize_cb'] = 'taxonomy_meta_box_sanitize_cb_input'; 463 break; 464 } 465 } 466 467 // Default taxonomy term. 468 if ( ! empty( $args['default_term'] ) ) { 469 if ( ! is_array( $args['default_term'] ) ) { 470 $args['default_term'] = array( 'name' => $args['default_term'] ); 471 } 472 $args['default_term'] = wp_parse_args( 473 $args['default_term'], 474 array( 475 'name' => '', 476 'slug' => '', 477 'description' => '', 478 ) 479 ); 480 } 481 482 foreach ( $args as $property_name => $property_value ) { 483 $this->$property_name = $property_value; 484 } 485 486 $this->labels = get_taxonomy_labels( $this ); 487 $this->label = $this->labels->name; 488 } 489 490 /** 491 * Adds the necessary rewrite rules for the taxonomy. 492 * 493 * @since 4.7.0 494 * 495 * @global WP $wp Current WordPress environment instance. 496 */ 497 public function add_rewrite_rules() { 498 /* @var WP $wp */ 499 global $wp; 500 501 // Non-publicly queryable taxonomies should not register query vars, except in the admin. 502 if ( false !== $this->query_var && $wp ) { 503 $wp->add_query_var( $this->query_var ); 504 } 505 506 if ( false !== $this->rewrite && ( is_admin() || get_option( 'permalink_structure' ) ) ) { 507 if ( $this->hierarchical && $this->rewrite['hierarchical'] ) { 508 $tag = '(.+?)'; 509 } else { 510 $tag = '([^/]+)'; 511 } 512 513 add_rewrite_tag( "%$this->name%", $tag, $this->query_var ? "{$this->query_var}=" : "taxonomy=$this->name&term=" ); 514 add_permastruct( $this->name, "{$this->rewrite['slug']}/%$this->name%", $this->rewrite ); 515 } 516 } 517 518 /** 519 * Removes any rewrite rules, permastructs, and rules for the taxonomy. 520 * 521 * @since 4.7.0 522 * 523 * @global WP $wp Current WordPress environment instance. 524 */ 525 public function remove_rewrite_rules() { 526 /* @var WP $wp */ 527 global $wp; 528 529 // Remove query var. 530 if ( false !== $this->query_var ) { 531 $wp->remove_query_var( $this->query_var ); 532 } 533 534 // Remove rewrite tags and permastructs. 535 if ( false !== $this->rewrite ) { 536 remove_rewrite_tag( "%$this->name%" ); 537 remove_permastruct( $this->name ); 538 } 539 } 540 541 /** 542 * Registers the ajax callback for the meta box. 543 * 544 * @since 4.7.0 545 */ 546 public function add_hooks() { 547 add_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' ); 548 } 549 550 /** 551 * Removes the ajax callback for the meta box. 552 * 553 * @since 4.7.0 554 */ 555 public function remove_hooks() { 556 remove_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' ); 557 } 558 559 /** 560 * Gets the REST API controller for this taxonomy. 561 * 562 * Will only instantiate the controller class once per request. 563 * 564 * @since 5.5.0 565 * 566 * @return WP_REST_Controller|null The controller instance, or null if the taxonomy 567 * is set not to show in rest. 568 */ 569 public function get_rest_controller() { 570 if ( ! $this->show_in_rest ) { 571 return null; 572 } 573 574 $class = $this->rest_controller_class ? $this->rest_controller_class : WP_REST_Terms_Controller::class; 575 576 if ( ! class_exists( $class ) ) { 577 return null; 578 } 579 580 if ( ! is_subclass_of( $class, WP_REST_Controller::class ) ) { 581 return null; 582 } 583 584 if ( ! $this->rest_controller ) { 585 $this->rest_controller = new $class( $this->name ); 586 } 587 588 if ( ! ( $this->rest_controller instanceof $class ) ) { 589 return null; 590 } 591 592 return $this->rest_controller; 593 } 594 595 /** 596 * Returns the default labels for taxonomies. 597 * 598 * @since 6.0.0 599 * 600 * @return (string|null)[][] The default labels for taxonomies. 601 */ 602 public static function get_default_labels() { 603 if ( ! empty( self::$default_labels ) ) { 604 return self::$default_labels; 605 } 606 607 $name_field_description = __( 'The name is how it appears on your site.' ); 608 $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.' ); 609 $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.' ); 610 $desc_field_description = __( 'The description is not prominent by default; however, some themes may show it.' ); 611 612 self::$default_labels = array( 613 'name' => array( _x( 'Tags', 'taxonomy general name' ), _x( 'Categories', 'taxonomy general name' ) ), 614 'singular_name' => array( _x( 'Tag', 'taxonomy singular name' ), _x( 'Category', 'taxonomy singular name' ) ), 615 'search_items' => array( __( 'Search Tags' ), __( 'Search Categories' ) ), 616 'popular_items' => array( __( 'Popular Tags' ), null ), 617 'all_items' => array( __( 'All Tags' ), __( 'All Categories' ) ), 618 'parent_item' => array( null, __( 'Parent Category' ) ), 619 'parent_item_colon' => array( null, __( 'Parent Category:' ) ), 620 'name_field_description' => array( $name_field_description, $name_field_description ), 621 'slug_field_description' => array( $slug_field_description, $slug_field_description ), 622 'parent_field_description' => array( null, $parent_field_description ), 623 'desc_field_description' => array( $desc_field_description, $desc_field_description ), 624 'edit_item' => array( __( 'Edit Tag' ), __( 'Edit Category' ) ), 625 'view_item' => array( __( 'View Tag' ), __( 'View Category' ) ), 626 'update_item' => array( __( 'Update Tag' ), __( 'Update Category' ) ), 627 'add_new_item' => array( __( 'Add New Tag' ), __( 'Add New Category' ) ), 628 'new_item_name' => array( __( 'New Tag Name' ), __( 'New Category Name' ) ), 629 'separate_items_with_commas' => array( __( 'Separate tags with commas' ), null ), 630 'add_or_remove_items' => array( __( 'Add or remove tags' ), null ), 631 'choose_from_most_used' => array( __( 'Choose from the most used tags' ), null ), 632 'not_found' => array( __( 'No tags found.' ), __( 'No categories found.' ) ), 633 'no_terms' => array( __( 'No tags' ), __( 'No categories' ) ), 634 'filter_by_item' => array( null, __( 'Filter by category' ) ), 635 'items_list_navigation' => array( __( 'Tags list navigation' ), __( 'Categories list navigation' ) ), 636 'items_list' => array( __( 'Tags list' ), __( 'Categories list' ) ), 637 /* translators: Tab heading when selecting from the most used terms. */ 638 'most_used' => array( _x( 'Most Used', 'tags' ), _x( 'Most Used', 'categories' ) ), 639 'back_to_items' => array( __( '← Go to Tags' ), __( '← Go to Categories' ) ), 640 'item_link' => array( 641 _x( 'Tag Link', 'navigation link block title' ), 642 _x( 'Category Link', 'navigation link block title' ), 643 ), 644 'item_link_description' => array( 645 _x( 'A link to a tag.', 'navigation link block description' ), 646 _x( 'A link to a category.', 'navigation link block description' ), 647 ), 648 ); 649 650 return self::$default_labels; 651 } 652 653 /** 654 * Resets the cache for the default labels. 655 * 656 * @since 6.0.0 657 */ 658 public static function reset_default_labels() { 659 self::$default_labels = array(); 660 } 661 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Tue Apr 23 08:20:01 2024 | Cross-referenced by PHPXref |