[ 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 object
  42       */
  43      public $labels;
  44  
  45      /**
  46       * A short descriptive summary of what the taxonomy is for.
  47       *
  48       * @since 4.7.0
  49       * @var string
  50       */
  51      public $description = '';
  52  
  53      /**
  54       * Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users.
  55       *
  56       * @since 4.7.0
  57       * @var bool
  58       */
  59      public $public = true;
  60  
  61      /**
  62       * Whether the taxonomy is publicly queryable.
  63       *
  64       * @since 4.7.0
  65       * @var bool
  66       */
  67      public $publicly_queryable = true;
  68  
  69      /**
  70       * Whether the taxonomy is hierarchical.
  71       *
  72       * @since 4.7.0
  73       * @var bool
  74       */
  75      public $hierarchical = false;
  76  
  77      /**
  78       * Whether to generate and allow a UI for managing terms in this taxonomy in the admin.
  79       *
  80       * @since 4.7.0
  81       * @var bool
  82       */
  83      public $show_ui = true;
  84  
  85      /**
  86       * Whether to show the taxonomy in the admin menu.
  87       *
  88       * If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown.
  89       *
  90       * @since 4.7.0
  91       * @var bool
  92       */
  93      public $show_in_menu = true;
  94  
  95      /**
  96       * Whether the taxonomy is available for selection in navigation menus.
  97       *
  98       * @since 4.7.0
  99       * @var bool
 100       */
 101      public $show_in_nav_menus = true;
 102  
 103      /**
 104       * Whether to list the taxonomy in the tag cloud widget controls.
 105       *
 106       * @since 4.7.0
 107       * @var bool
 108       */
 109      public $show_tagcloud = true;
 110  
 111      /**
 112       * Whether to show the taxonomy in the quick/bulk edit panel.
 113       *
 114       * @since 4.7.0
 115       * @var bool
 116       */
 117      public $show_in_quick_edit = true;
 118  
 119      /**
 120       * Whether to display a column for the taxonomy on its post type listing screens.
 121       *
 122       * @since 4.7.0
 123       * @var bool
 124       */
 125      public $show_admin_column = false;
 126  
 127      /**
 128       * The callback function for the meta box display.
 129       *
 130       * @since 4.7.0
 131       * @var bool|callable
 132       */
 133      public $meta_box_cb = null;
 134  
 135      /**
 136       * The callback function for sanitizing taxonomy data saved from a meta box.
 137       *
 138       * @since 5.1.0
 139       * @var callable
 140       */
 141      public $meta_box_sanitize_cb = null;
 142  
 143      /**
 144       * An array of object types this taxonomy is registered for.
 145       *
 146       * @since 4.7.0
 147       * @var array
 148       */
 149      public $object_type = null;
 150  
 151      /**
 152       * Capabilities for this taxonomy.
 153       *
 154       * @since 4.7.0
 155       * @var object
 156       */
 157      public $cap;
 158  
 159      /**
 160       * Rewrites information for this taxonomy.
 161       *
 162       * @since 4.7.0
 163       * @var array|false
 164       */
 165      public $rewrite;
 166  
 167      /**
 168       * Query var string for this taxonomy.
 169       *
 170       * @since 4.7.0
 171       * @var string|false
 172       */
 173      public $query_var;
 174  
 175      /**
 176       * Function that will be called when the count is updated.
 177       *
 178       * @since 4.7.0
 179       * @var callable
 180       */
 181      public $update_count_callback;
 182  
 183      /**
 184       * Function that will be called when the count is modified by an amount.
 185       *
 186       * @since 5.6.0
 187       * @var callable
 188       */
 189      public $update_count_by_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 controller for this taxonomy's REST API endpoints.
 212       *
 213       * Custom controllers must extend WP_REST_Controller.
 214       *
 215       * @since 4.7.4
 216       * @var string|bool $rest_controller_class
 217       */
 218      public $rest_controller_class;
 219  
 220      /**
 221       * The default term name for this taxonomy. If you pass an array you have
 222       * to set 'name' and optionally 'slug' and 'description'.
 223       *
 224       * @since 5.5.0
 225       * @var array|string
 226       */
 227      public $default_term;
 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       * Whether it is a built-in taxonomy.
 241       *
 242       * @since 4.7.0
 243       * @var bool
 244       */
 245      public $_builtin;
 246  
 247      /**
 248       * Constructor.
 249       *
 250       * @since 4.7.0
 251       *
 252       * @global WP $wp Current WordPress environment instance.
 253       *
 254       * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters.
 255       * @param array|string $object_type Name of the object type for the taxonomy object.
 256       * @param array|string $args        Optional. Array or query string of arguments for registering a taxonomy.
 257       *                                  Default empty array.
 258       */
 259  	public function __construct( $taxonomy, $object_type, $args = array() ) {
 260          $this->name = $taxonomy;
 261  
 262          $this->set_props( $object_type, $args );
 263      }
 264  
 265      /**
 266       * Sets taxonomy properties.
 267       *
 268       * @since 4.7.0
 269       *
 270       * @param array|string $object_type Name of the object type for the taxonomy object.
 271       * @param array|string $args        Array or query string of arguments for registering a taxonomy.
 272       */
 273  	public function set_props( $object_type, $args ) {
 274          $args = wp_parse_args( $args );
 275  
 276          /**
 277           * Filters the arguments for registering a taxonomy.
 278           *
 279           * @since 4.4.0
 280           *
 281           * @param array    $args        Array of arguments for registering a taxonomy.
 282           * @param string   $taxonomy    Taxonomy key.
 283           * @param string[] $object_type Array of names of object types for the taxonomy.
 284           */
 285          $args = apply_filters( 'register_taxonomy_args', $args, $this->name, (array) $object_type );
 286  
 287          $defaults = array(
 288              'labels'                   => array(),
 289              'description'              => '',
 290              'public'                   => true,
 291              'publicly_queryable'       => null,
 292              'hierarchical'             => false,
 293              'show_ui'                  => null,
 294              'show_in_menu'             => null,
 295              'show_in_nav_menus'        => null,
 296              'show_tagcloud'            => null,
 297              'show_in_quick_edit'       => null,
 298              'show_admin_column'        => false,
 299              'meta_box_cb'              => null,
 300              'meta_box_sanitize_cb'     => null,
 301              'capabilities'             => array(),
 302              'rewrite'                  => true,
 303              'query_var'                => $this->name,
 304              'update_count_callback'    => '',
 305              'update_count_by_callback' => '',
 306              'show_in_rest'             => false,
 307              'rest_base'                => false,
 308              'rest_controller_class'    => false,
 309              'default_term'             => null,
 310              '_builtin'                 => false,
 311          );
 312  
 313          $args = array_merge( $defaults, $args );
 314  
 315          // If not set, default to the setting for 'public'.
 316          if ( null === $args['publicly_queryable'] ) {
 317              $args['publicly_queryable'] = $args['public'];
 318          }
 319  
 320          if ( false !== $args['query_var'] && ( is_admin() || false !== $args['publicly_queryable'] ) ) {
 321              if ( true === $args['query_var'] ) {
 322                  $args['query_var'] = $this->name;
 323              } else {
 324                  $args['query_var'] = sanitize_title_with_dashes( $args['query_var'] );
 325              }
 326          } else {
 327              // Force 'query_var' to false for non-public taxonomies.
 328              $args['query_var'] = false;
 329          }
 330  
 331          if ( false !== $args['rewrite'] && ( is_admin() || get_option( 'permalink_structure' ) ) ) {
 332              $args['rewrite'] = wp_parse_args(
 333                  $args['rewrite'],
 334                  array(
 335                      'with_front'   => true,
 336                      'hierarchical' => false,
 337                      'ep_mask'      => EP_NONE,
 338                  )
 339              );
 340  
 341              if ( empty( $args['rewrite']['slug'] ) ) {
 342                  $args['rewrite']['slug'] = sanitize_title_with_dashes( $this->name );
 343              }
 344          }
 345  
 346          // If not set, default to the setting for 'public'.
 347          if ( null === $args['show_ui'] ) {
 348              $args['show_ui'] = $args['public'];
 349          }
 350  
 351          // If not set, default to the setting for 'show_ui'.
 352          if ( null === $args['show_in_menu'] || ! $args['show_ui'] ) {
 353              $args['show_in_menu'] = $args['show_ui'];
 354          }
 355  
 356          // If not set, default to the setting for 'public'.
 357          if ( null === $args['show_in_nav_menus'] ) {
 358              $args['show_in_nav_menus'] = $args['public'];
 359          }
 360  
 361          // If not set, default to the setting for 'show_ui'.
 362          if ( null === $args['show_tagcloud'] ) {
 363              $args['show_tagcloud'] = $args['show_ui'];
 364          }
 365  
 366          // If not set, default to the setting for 'show_ui'.
 367          if ( null === $args['show_in_quick_edit'] ) {
 368              $args['show_in_quick_edit'] = $args['show_ui'];
 369          }
 370  
 371          $default_caps = array(
 372              'manage_terms' => 'manage_categories',
 373              'edit_terms'   => 'manage_categories',
 374              'delete_terms' => 'manage_categories',
 375              'assign_terms' => 'edit_posts',
 376          );
 377  
 378          $args['cap'] = (object) array_merge( $default_caps, $args['capabilities'] );
 379          unset( $args['capabilities'] );
 380  
 381          $args['object_type'] = array_unique( (array) $object_type );
 382  
 383          // If not set, use the default meta box.
 384          if ( null === $args['meta_box_cb'] ) {
 385              if ( $args['hierarchical'] ) {
 386                  $args['meta_box_cb'] = 'post_categories_meta_box';
 387              } else {
 388                  $args['meta_box_cb'] = 'post_tags_meta_box';
 389              }
 390          }
 391  
 392          $args['name'] = $this->name;
 393  
 394          // Default meta box sanitization callback depends on the value of 'meta_box_cb'.
 395          if ( null === $args['meta_box_sanitize_cb'] ) {
 396              switch ( $args['meta_box_cb'] ) {
 397                  case 'post_categories_meta_box':
 398                      $args['meta_box_sanitize_cb'] = 'taxonomy_meta_box_sanitize_cb_checkboxes';
 399                      break;
 400  
 401                  case 'post_tags_meta_box':
 402                  default:
 403                      $args['meta_box_sanitize_cb'] = 'taxonomy_meta_box_sanitize_cb_input';
 404                      break;
 405              }
 406          }
 407  
 408          // Default taxonomy term.
 409          if ( ! empty( $args['default_term'] ) ) {
 410              if ( ! is_array( $args['default_term'] ) ) {
 411                  $args['default_term'] = array( 'name' => $args['default_term'] );
 412              }
 413              $args['default_term'] = wp_parse_args(
 414                  $args['default_term'],
 415                  array(
 416                      'name'        => '',
 417                      'slug'        => '',
 418                      'description' => '',
 419                  )
 420              );
 421          }
 422  
 423          // If generic update callback is defined but increment/decrement callback is not.
 424          if (
 425              ! empty( $args['update_count_callback'] ) &&
 426              is_callable( $args['update_count_callback'] ) &&
 427              empty( $args['update_count_by_callback'] )
 428          ) {
 429              $args['update_count_by_callback'] = function( $tt_ids, $taxonomy ) use ( $args ) {
 430                  return call_user_func( $args['update_count_callback'], $tt_ids, $taxonomy );
 431              };
 432          }
 433  
 434          foreach ( $args as $property_name => $property_value ) {
 435              $this->$property_name = $property_value;
 436          }
 437  
 438          $this->labels = get_taxonomy_labels( $this );
 439          $this->label  = $this->labels->name;
 440      }
 441  
 442      /**
 443       * Adds the necessary rewrite rules for the taxonomy.
 444       *
 445       * @since 4.7.0
 446       *
 447       * @global WP $wp Current WordPress environment instance.
 448       */
 449  	public function add_rewrite_rules() {
 450          /* @var WP $wp */
 451          global $wp;
 452  
 453          // Non-publicly queryable taxonomies should not register query vars, except in the admin.
 454          if ( false !== $this->query_var && $wp ) {
 455              $wp->add_query_var( $this->query_var );
 456          }
 457  
 458          if ( false !== $this->rewrite && ( is_admin() || get_option( 'permalink_structure' ) ) ) {
 459              if ( $this->hierarchical && $this->rewrite['hierarchical'] ) {
 460                  $tag = '(.+?)';
 461              } else {
 462                  $tag = '([^/]+)';
 463              }
 464  
 465              add_rewrite_tag( "%$this->name%", $tag, $this->query_var ? "{$this->query_var}=" : "taxonomy=$this->name&term=" );
 466              add_permastruct( $this->name, "{$this->rewrite['slug']}/%$this->name%", $this->rewrite );
 467          }
 468      }
 469  
 470      /**
 471       * Removes any rewrite rules, permastructs, and rules for the taxonomy.
 472       *
 473       * @since 4.7.0
 474       *
 475       * @global WP $wp Current WordPress environment instance.
 476       */
 477  	public function remove_rewrite_rules() {
 478          /* @var WP $wp */
 479          global $wp;
 480  
 481          // Remove query var.
 482          if ( false !== $this->query_var ) {
 483              $wp->remove_query_var( $this->query_var );
 484          }
 485  
 486          // Remove rewrite tags and permastructs.
 487          if ( false !== $this->rewrite ) {
 488              remove_rewrite_tag( "%$this->name%" );
 489              remove_permastruct( $this->name );
 490          }
 491      }
 492  
 493      /**
 494       * Registers the ajax callback for the meta box.
 495       *
 496       * @since 4.7.0
 497       */
 498  	public function add_hooks() {
 499          add_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' );
 500      }
 501  
 502      /**
 503       * Removes the ajax callback for the meta box.
 504       *
 505       * @since 4.7.0
 506       */
 507  	public function remove_hooks() {
 508          remove_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' );
 509      }
 510  
 511      /**
 512       * Gets the REST API controller for this taxonomy.
 513       *
 514       * Will only instantiate the controller class once per request.
 515       *
 516       * @since 5.5.0
 517       *
 518       * @return WP_REST_Controller|null The controller instance, or null if the taxonomy
 519       *                                 is set not to show in rest.
 520       */
 521  	public function get_rest_controller() {
 522          if ( ! $this->show_in_rest ) {
 523              return null;
 524          }
 525  
 526          $class = $this->rest_controller_class ? $this->rest_controller_class : WP_REST_Terms_Controller::class;
 527  
 528          if ( ! class_exists( $class ) ) {
 529              return null;
 530          }
 531  
 532          if ( ! is_subclass_of( $class, WP_REST_Controller::class ) ) {
 533              return null;
 534          }
 535  
 536          if ( ! $this->rest_controller ) {
 537              $this->rest_controller = new $class( $this->name );
 538          }
 539  
 540          if ( ! ( $this->rest_controller instanceof $class ) ) {
 541              return null;
 542          }
 543  
 544          return $this->rest_controller;
 545      }
 546  }


Generated: Sun Oct 25 01:00:03 2020 Cross-referenced by PHPXref 0.7.1