[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> class-wp-taxonomy.php (source)

   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  final class WP_Taxonomy {
  16      /**
  17       * Taxonomy key.
  18       *
  19       * @since 4.7.0
  20       * @var string
  21       */
  22      public $name;
  23  
  24      /**
  25       * Name of the taxonomy shown in the menu. Usually plural.
  26       *
  27       * @since 4.7.0
  28       * @var string
  29       */
  30      public $label;
  31  
  32      /**
  33       * Labels object for this taxonomy.
  34       *
  35       * If not set, tag labels are inherited for non-hierarchical types
  36       * and category labels for hierarchical ones.
  37       *
  38       * @see get_taxonomy_labels()
  39       *
  40       * @since 4.7.0
  41       * @var stdClass
  42       */
  43      public $labels;
  44  
  45      /**
  46       * Default labels.
  47       *
  48       * @since 6.0.0
  49       * @var (string|null)[][] $default_labels
  50       */
  51      protected static $default_labels = array();
  52  
  53      /**
  54       * A short descriptive summary of what the taxonomy is for.
  55       *
  56       * @since 4.7.0
  57       * @var string
  58       */
  59      public $description = '';
  60  
  61      /**
  62       * Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users.
  63       *
  64       * @since 4.7.0
  65       * @var bool
  66       */
  67      public $public = true;
  68  
  69      /**
  70       * Whether the taxonomy is publicly queryable.
  71       *
  72       * @since 4.7.0
  73       * @var bool
  74       */
  75      public $publicly_queryable = true;
  76  
  77      /**
  78       * Whether the taxonomy is hierarchical.
  79       *
  80       * @since 4.7.0
  81       * @var bool
  82       */
  83      public $hierarchical = false;
  84  
  85      /**
  86       * Whether to generate and allow a UI for managing terms in this taxonomy in the admin.
  87       *
  88       * @since 4.7.0
  89       * @var bool
  90       */
  91      public $show_ui = true;
  92  
  93      /**
  94       * Whether to show the taxonomy in the admin menu.
  95       *
  96       * If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown.
  97       *
  98       * @since 4.7.0
  99       * @var bool
 100       */
 101      public $show_in_menu = true;
 102  
 103      /**
 104       * Whether the taxonomy is available for selection in navigation menus.
 105       *
 106       * @since 4.7.0
 107       * @var bool
 108       */
 109      public $show_in_nav_menus = true;
 110  
 111      /**
 112       * Whether to list the taxonomy in the tag cloud widget controls.
 113       *
 114       * @since 4.7.0
 115       * @var bool
 116       */
 117      public $show_tagcloud = true;
 118  
 119      /**
 120       * Whether to show the taxonomy in the quick/bulk edit panel.
 121       *
 122       * @since 4.7.0
 123       * @var bool
 124       */
 125      public $show_in_quick_edit = true;
 126  
 127      /**
 128       * Whether to display a column for the taxonomy on its post type listing screens.
 129       *
 130       * @since 4.7.0
 131       * @var bool
 132       */
 133      public $show_admin_column = false;
 134  
 135      /**
 136       * The callback function for the meta box display.
 137       *
 138       * @since 4.7.0
 139       * @var bool|callable
 140       */
 141      public $meta_box_cb = null;
 142  
 143      /**
 144       * The callback function for sanitizing taxonomy data saved from a meta box.
 145       *
 146       * @since 5.1.0
 147       * @var callable
 148       */
 149      public $meta_box_sanitize_cb = null;
 150  
 151      /**
 152       * An array of object types this taxonomy is registered for.
 153       *
 154       * @since 4.7.0
 155       * @var string[]
 156       */
 157      public $object_type = null;
 158  
 159      /**
 160       * Capabilities for this taxonomy.
 161       *
 162       * @since 4.7.0
 163       * @var stdClass
 164       */
 165      public $cap;
 166  
 167      /**
 168       * Rewrites information for this taxonomy.
 169       *
 170       * @since 4.7.0
 171       * @var array|false
 172       */
 173      public $rewrite;
 174  
 175      /**
 176       * Query var string for this taxonomy.
 177       *
 178       * @since 4.7.0
 179       * @var string|false
 180       */
 181      public $query_var;
 182  
 183      /**
 184       * Function that will be called when the count is updated.
 185       *
 186       * @since 4.7.0
 187       * @var callable
 188       */
 189      public $update_count_callback;
 190  
 191      /**
 192       * Whether this taxonomy should appear in the REST API.
 193       *
 194       * Default false. If true, standard endpoints will be registered with
 195       * respect to $rest_base and $rest_controller_class.
 196       *
 197       * @since 4.7.4
 198       * @var bool $show_in_rest
 199       */
 200      public $show_in_rest;
 201  
 202      /**
 203       * The base path for this taxonomy's REST API endpoints.
 204       *
 205       * @since 4.7.4
 206       * @var string|bool $rest_base
 207       */
 208      public $rest_base;
 209  
 210      /**
 211       * The namespace for this taxonomy's REST API endpoints.
 212       *
 213       * @since 5.9.0
 214       * @var string|bool $rest_namespace
 215       */
 216      public $rest_namespace;
 217  
 218      /**
 219       * The controller for this taxonomy's REST API endpoints.
 220       *
 221       * Custom controllers must extend WP_REST_Controller.
 222       *
 223       * @since 4.7.4
 224       * @var string|bool $rest_controller_class
 225       */
 226      public $rest_controller_class;
 227  
 228      /**
 229       * The controller instance for this taxonomy's REST API endpoints.
 230       *
 231       * Lazily computed. Should be accessed using {@see WP_Taxonomy::get_rest_controller()}.
 232       *
 233       * @since 5.5.0
 234       * @var WP_REST_Controller $rest_controller
 235       */
 236      public $rest_controller;
 237  
 238      /**
 239       * The default term name for this taxonomy. If you pass an array you have
 240       * to set 'name' and optionally 'slug' and 'description'.
 241       *
 242       * @since 5.5.0
 243       * @var array|string
 244       */
 245      public $default_term;
 246  
 247      /**
 248       * Whether terms in this taxonomy should be sorted in the order they are provided to `wp_set_object_terms()`.
 249       *
 250       * Use this in combination with `'orderby' => 'term_order'` when fetching terms.
 251       *
 252       * @since 2.5.0
 253       * @var bool|null
 254       */
 255      public $sort = null;
 256  
 257      /**
 258       * Array of arguments to automatically use inside `wp_get_object_terms()` for this taxonomy.
 259       *
 260       * @since 2.6.0
 261       * @var array|null
 262       */
 263      public $args = null;
 264  
 265      /**
 266       * Whether it is a built-in taxonomy.
 267       *
 268       * @since 4.7.0
 269       * @var bool
 270       */
 271      public $_builtin;
 272  
 273      /**
 274       * Constructor.
 275       *
 276       * See the register_taxonomy() function for accepted arguments for `$args`.
 277       *
 278       * @since 4.7.0
 279       *
 280       * @global WP $wp Current WordPress environment instance.
 281       *
 282       * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters.
 283       * @param array|string $object_type Name of the object type for the taxonomy object.
 284       * @param array|string $args        Optional. Array or query string of arguments for registering a taxonomy.
 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 &#8220;slug&#8221; 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( __( '&larr; Go to Tags' ), __( '&larr; 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  }


Generated: Sat Nov 23 01:00:02 2024 Cross-referenced by PHPXref 0.7.1