wp-includes/class-wp-taxonomy.php

   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          * @access public
  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          * @access public
  30          * @var string
  31          */
  32         public $label;
  33
  34         /**
  35          * An array of labels for this taxonomy.
  36          *
  37          * @since 4.7.0
  38          * @access public
  39          * @var object
  40          */
  41         public $labels = array();
  42
  43         /**
  44          * A short descriptive summary of what the taxonomy is for.
  45          *
  46          * @since 4.7.0
  47          * @access public
  48          * @var string
  49          */
  50         public $description = '';
  51
  52         /**
  53          * Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users.
  54          *
  55          * @since 4.7.0
  56          * @access public
  57          * @var bool
  58          */
  59         public $public = true;
  60
  61         /**
  62          * Whether the taxonomy is publicly queryable.
  63          *
  64          * @since 4.7.0
  65          * @access public
  66          * @var bool
  67          */
  68         public $publicly_queryable = true;
  69
  70         /**
  71          * Whether the taxonomy is hierarchical.
  72          *
  73          * @since 4.7.0
  74          * @access public
  75          * @var bool
  76          */
  77         public $hierarchical = false;
  78
  79         /**
  80          * Whether to generate and allow a UI for managing terms in this taxonomy in the admin.
  81          *
  82          * @since 4.7.0
  83          * @access public
  84          * @var bool
  85          */
  86         public $show_ui = true;
  87
  88         /**
  89          * Whether to show the taxonomy in the admin menu.
  90          *
  91          * If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown.
  92          *
  93          * @since 4.7.0
  94          * @access public
  95          * @var bool
  96          */
  97         public $show_in_menu = true;
  98
  99         /**
 100          * Whether the taxonomy is available for selection in navigation menus.
 101          *
 102          * @since 4.7.0
 103          * @access public
 104          * @var bool
 105          */
 106         public $show_in_nav_menus = true;
 107
 108         /**
 109          * Whether to list the taxonomy in the tag cloud widget controls.
 110          *
 111          * @since 4.7.0
 112          * @access public
 113          * @var bool
 114          */
 115         public $show_tagcloud = true;
 116
 117         /**
 118          * Whether to show the taxonomy in the quick/bulk edit panel.
 119          *
 120          * @since 4.7.0
 121          * @access public
 122          * @var bool
 123          */
 124         public $show_in_quick_edit = true;
 125
 126         /**
 127          * Whether to display a column for the taxonomy on its post type listing screens.
 128          *
 129          * @since 4.7.0
 130          * @access public
 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          * @access public
 140          * @var bool|callable
 141          */
 142         public $meta_box_cb = null;
 143
 144         /**
 145          * An array of object types this taxonomy is registered for.
 146          *
 147          * @since 4.7.0
 148          * @access public
 149          * @var array
 150          */
 151         public $object_type = null;
 152
 153         /**
 154          * Capabilities for this taxonomy.
 155          *
 156          * @since 4.7.0
 157          * @access public
 158          * @var array
 159          */
 160         public $cap;
 161
 162         /**
 163          * Rewrites information for this taxonomy.
 164          *
 165          * @since 4.7.0
 166          * @access public
 167          * @var array|false
 168          */
 169         public $rewrite;
 170
 171         /**
 172          * Query var string for this taxonomy.
 173          *
 174          * @since 4.7.0
 175          * @access public
 176          * @var string|false
 177          */
 178         public $query_var;
 179
 180         /**
 181          * Function that will be called when the count is updated.
 182          *
 183          * @since 4.7.0
 184          * @access public
 185          * @var callable
 186          */
 187         public $update_count_callback;
 188
 189         /**
 190          * Whether it is a built-in taxonomy.
 191          *
 192          * @since 4.7.0
 193          * @access public
 194          * @var bool
 195          */
 196         public $_builtin;
 197
 198         /**
 199          * Constructor.
 200          *
 201          * @since 4.7.0
 202          * @access public
 203          *
 204          * @global WP $wp WP instance.
 205          *
 206          * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters.
 207          * @param array|string $object_type Name of the object type for the taxonomy object.
 208          * @param array|string $args        Optional. Array or query string of arguments for registering a taxonomy.
 209          *                                  Default empty array.
 210          */
 211         public function __construct( $taxonomy, $object_type, $args = array() ) {
 212                 $this->name = $taxonomy;
 213
 214                 $this->set_props( $object_type, $args );
 215         }
 216
 217         /**
 218          * Sets taxonomy properties.
 219          *
 220          * @since 4.7.0
 221          * @access public
 222          *
 223          * @param array|string $object_type Name of the object type for the taxonomy object.
 224          * @param array|string $args        Array or query string of arguments for registering a taxonomy.
 225          */
 226         public function set_props( $object_type, $args ) {
 227                 $args = wp_parse_args( $args );
 228
 229                 /**
 230                  * Filters the arguments for registering a taxonomy.
 231                  *
 232                  * @since 4.4.0
 233                  *
 234                  * @param array  $args        Array of arguments for registering a taxonomy.
 235                  * @param string $taxonomy    Taxonomy key.
 236                  * @param array  $object_type Array of names of object types for the taxonomy.
 237                  */
 238                 $args = apply_filters( 'register_taxonomy_args', $args, $this->name, (array) $object_type );
 239
 240                 $defaults = array(
 241                         'labels'                => array(),
 242                         'description'           => '',
 243                         'public'                => true,
 244                         'publicly_queryable'    => null,
 245                         'hierarchical'          => false,
 246                         'show_ui'               => null,
 247                         'show_in_menu'          => null,
 248                         'show_in_nav_menus'     => null,
 249                         'show_tagcloud'         => null,
 250                         'show_in_quick_edit'    => null,
 251                         'show_admin_column'     => false,
 252                         'meta_box_cb'           => null,
 253                         'capabilities'          => array(),
 254                         'rewrite'               => true,
 255                         'query_var'             => $this->name,
 256                         'update_count_callback' => '',
 257                         '_builtin'              => false,
 258                 );
 259
 260                 $args = array_merge( $defaults, $args );
 261
 262                 // If not set, default to the setting for public.
 263                 if ( null === $args['publicly_queryable'] ) {
 264                         $args['publicly_queryable'] = $args['public'];
 265                 }
 266
 267                 if ( false !== $args['query_var'] && ( is_admin() || false !== $args['publicly_queryable'] ) ) {
 268                         if ( true === $args['query_var'] ) {
 269                                 $args['query_var'] = $this->name;
 270                         } else {
 271                                 $args['query_var'] = sanitize_title_with_dashes( $args['query_var'] );
 272                         }
 273                 } else {
 274                         // Force query_var to false for non-public taxonomies.
 275                         $args['query_var'] = false;
 276                 }
 277
 278                 if ( false !== $args['rewrite'] && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) {
 279                         $args['rewrite'] = wp_parse_args( $args['rewrite'], array(
 280                                 'with_front'   => true,
 281                                 'hierarchical' => false,
 282                                 'ep_mask'      => EP_NONE,
 283                         ) );
 284
 285                         if ( empty( $args['rewrite']['slug'] ) ) {
 286                                 $args['rewrite']['slug'] = sanitize_title_with_dashes( $this->name );
 287                         }
 288                 }
 289
 290                 // If not set, default to the setting for public.
 291                 if ( null === $args['show_ui'] ) {
 292                         $args['show_ui'] = $args['public'];
 293                 }
 294
 295                 // If not set, default to the setting for show_ui.
 296                 if ( null === $args['show_in_menu'] || ! $args['show_ui'] ) {
 297                         $args['show_in_menu'] = $args['show_ui'];
 298                 }
 299
 300                 // If not set, default to the setting for public.
 301                 if ( null === $args['show_in_nav_menus'] ) {
 302                         $args['show_in_nav_menus'] = $args['public'];
 303                 }
 304
 305                 // If not set, default to the setting for show_ui.
 306                 if ( null === $args['show_tagcloud'] ) {
 307                         $args['show_tagcloud'] = $args['show_ui'];
 308                 }
 309
 310                 // If not set, default to the setting for show_ui.
 311                 if ( null === $args['show_in_quick_edit'] ) {
 312                         $args['show_in_quick_edit'] = $args['show_ui'];
 313                 }
 314
 315                 $default_caps = array(
 316                         'manage_terms' => 'manage_categories',
 317                         'edit_terms'   => 'manage_categories',
 318                         'delete_terms' => 'manage_categories',
 319                         'assign_terms' => 'edit_posts',
 320                 );
 321
 322                 $args['cap'] = (object) array_merge( $default_caps, $args['capabilities'] );
 323                 unset( $args['capabilities'] );
 324
 325                 $args['object_type'] = array_unique( (array) $object_type );
 326
 327                 // If not set, use the default meta box
 328                 if ( null === $args['meta_box_cb'] ) {
 329                         if ( $args['hierarchical'] ) {
 330                                 $args['meta_box_cb'] = 'post_categories_meta_box';
 331                         } else {
 332                                 $args['meta_box_cb'] = 'post_tags_meta_box';
 333                         }
 334                 }
 335
 336                 foreach ( $args as $property_name => $property_value ) {
 337                         $this->$property_name = $property_value;
 338                 }
 339
 340                 $this->labels = get_taxonomy_labels( $this );
 341                 $this->label = $this->labels->name;
 342         }
 343
 344         /**
 345          * Adds the necessary rewrite rules for the taxonomy.
 346          *
 347          * @since 4.7.0
 348          * @access public
 349          *
 350          * @global WP $wp Current WordPress environment instance.
 351          */
 352         public function add_rewrite_rules() {
 353                 /* @var WP $wp */
 354                 global $wp;
 355
 356                 // Non-publicly queryable taxonomies should not register query vars, except in the admin.
 357                 if ( false !== $this->query_var && $wp ) {
 358                         $wp->add_query_var( $this->query_var );
 359                 }
 360
 361                 if ( false !== $this->rewrite && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) {
 362                         if ( $this->hierarchical && $this->rewrite['hierarchical'] ) {
 363                                 $tag = '(.+?)';
 364                         } else {
 365                                 $tag = '([^/]+)';
 366                         }
 367
 368                         add_rewrite_tag( "%$this->name%", $tag, $this->query_var ? "{$this->query_var}=" : "taxonomy=$this->name&term=" );
 369                         add_permastruct( $this->name, "{$this->rewrite['slug']}/%$this->name%", $this->rewrite );
 370                 }
 371         }
 372
 373         /**
 374          * Removes any rewrite rules, permastructs, and rules for the taxonomy.
 375          *
 376          * @since 4.7.0
 377          * @access public
 378          *
 379          * @global WP $wp Current WordPress environment instance.
 380          */
 381         public function remove_rewrite_rules() {
 382                 /* @var WP $wp */
 383                 global $wp;
 384
 385                 // Remove query var.
 386                 if ( false !== $this->query_var ) {
 387                         $wp->remove_query_var( $this->query_var );
 388                 }
 389
 390                 // Remove rewrite tags and permastructs.
 391                 if ( false !== $this->rewrite ) {
 392                         remove_rewrite_tag( "%$this->name%" );
 393                         remove_permastruct( $this->name );
 394                 }
 395         }
 396
 397         /**
 398          * Registers the ajax callback for the meta box.
 399          *
 400          * @since 4.7.0
 401          * @access public
 402          */
 403         public function add_hooks() {
 404                 add_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' );
 405         }
 406
 407         /**
 408          * Removes the ajax callback for the meta box.
 409          *
 410          * @since 4.7.0
 411          * @access public
 412          */
 413         public function remove_hooks() {
 414                 remove_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' );
 415         }
 416 }