Core class used for interacting with taxonomies. Represents a registered taxonomy and its configuration.

Source: wp-includes/class-wp-taxonomy.php
Since: 4.7.0

Class Declaration

#[AllowDynamicProperties]
final class WP_Taxonomy

Properties

Static Properties

Methods

__construct()

Constructor. Instantiates a taxonomy object.

public function __construct( string $taxonomy, array|string $object_type, array|string $args = array() )

Note: Do not instantiate directly. Use register_taxonomy().

set_props()

Sets taxonomy properties.

public function set_props( string|string[] $object_type, array|string $args ): void

Filters Applied:

• register_taxonomy_args — Filters registration arguments
• register_{$taxonomy}_taxonomy_args — Filters arguments for specific taxonomy

Processing:

1. Parses and applies default arguments
2. Sets publicly_queryable from public if not specified
3. Configures query_var and rewrite rules
4. Inherits show_ui, show_in_menu, show_in_nav_menus, show_tagcloud, show_in_quick_edit from defaults
5. Sets default capabilities
6. Configures meta box callbacks
7. Processes default_term configuration
8. Generates labels via get_taxonomy_labels()

add_rewrite_rules()

Adds the necessary rewrite rules for the taxonomy.

public function add_rewrite_rules(): void

Behavior:

• Adds query var if query_var is set and not in admin
• Adds rewrite tag and permastruct if rewrite is configured
• Uses hierarchical tag (.+?) or non-hierarchical ([^/]+) based on settings

remove_rewrite_rules()

Removes any rewrite rules, permastructs, and rules for the taxonomy.

public function remove_rewrite_rules(): void

Behavior:

• Removes query var from $wp->query_vars
• Removes rewrite tag and permastruct

add_hooks()

Registers the ajax callback for the meta box.

public function add_hooks(): void

Behavior:

Adds filter wp_ajax_add-{$taxonomy} pointing to _wp_ajax_add_hierarchical_term.

remove_hooks()

Removes the ajax callback for the meta box.

public function remove_hooks(): void

Behavior:

Removes filter wp_ajax_add-{$taxonomy}.

get_rest_controller()

Gets the REST API controller for this taxonomy.

public function get_rest_controller(): WP_REST_Controller|null

Returns: Controller instance, or null if show_in_rest is false.

Behavior:

• Returns null if show_in_rest is falsy
• Uses rest_controller_class if set, otherwise WP_REST_Terms_Controller
• Validates class exists and extends WP_REST_Controller
• Lazily instantiates and caches controller

get_default_labels()

Returns the default labels for taxonomies.

public static function get_default_labels(): (string|null)[][]

Returns: Associative array of label keys to arrays of [non-hierarchical, hierarchical] values.

Label Keys:

reset_default_labels()

Resets the cache for the default labels.

public static function reset_default_labels(): void

Behavior:

Clears self::$default_labels to force regeneration on next access.

Capabilities Object

The $cap property contains:

Rewrite Configuration

When $rewrite is an array:

Usage Example

// Taxonomy is created via register_taxonomy(), not directly
add_action( 'init', function() {
    register_taxonomy( 'genre', 'book', array(
        'labels' => array(
            'name' => 'Genres',
            'singular_name' => 'Genre',
        ),
        'hierarchical' => true,
        'show_in_rest' => true,
        'rewrite' => array( 'slug' => 'book-genre' ),
    ) );
} );

// Get taxonomy object
$taxonomy = get_taxonomy( 'genre' );

// Access properties
echo $taxonomy->name;           // 'genre'
echo $taxonomy->labels->name;   // 'Genres'
echo $taxonomy->hierarchical;   // true

// Get REST controller
$controller = $taxonomy->get_rest_controller();