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]
16final 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 Tag' ), __( 'Add 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}
662