Core functions for taxonomy and term registration, retrieval, and management.

Source: wp-includes/taxonomy.php

Taxonomy Registration

register_taxonomy()

Creates or modifies a taxonomy object.

register_taxonomy( string $taxonomy, array|string $object_type, array|string $args = array() ): WP_Taxonomy|WP_Error

Note: Do not use before the init hook.

Args

Capabilities Array

Rewrite Array

Returns: WP_Taxonomy on success, WP_Error on failure.

Example:

add_action( 'init', function() {
    register_taxonomy( 'genre', array( 'book', 'movie' ), array(
        'labels'            => array(
            'name'          => __( 'Genres' ),
            'singular_name' => __( 'Genre' ),
        ),
        'hierarchical'      => true,
        'show_in_rest'      => true,
        'show_admin_column' => true,
        'rewrite'           => array( 'slug' => 'genre' ),
    ) );
} );

unregister_taxonomy()

Unregisters a taxonomy. Cannot unregister built-in taxonomies.

unregister_taxonomy( string $taxonomy ): true|WP_Error

Returns: true on success, WP_Error on failure.

register_taxonomy_for_object_type()

Adds an already registered taxonomy to an object type.

register_taxonomy_for_object_type( string $taxonomy, string $object_type ): bool

Returns: true on success, false if taxonomy or object type doesn’t exist.

unregister_taxonomy_for_object_type()

Removes an already registered taxonomy from an object type.

unregister_taxonomy_for_object_type( string $taxonomy, string $object_type ): bool

Returns: true on success, false on failure.

Taxonomy Retrieval

get_taxonomy()

Retrieves the taxonomy object.

get_taxonomy( string $taxonomy ): WP_Taxonomy|false

Returns: WP_Taxonomy object or false if not found.

get_taxonomies()

Retrieves a list of registered taxonomy names or objects.

get_taxonomies( array $args = array(), string $output = 'names', string $operator = 'and' ): string[]|WP_Taxonomy[]

Returns: Array of taxonomy names or WP_Taxonomy objects.

Example:

// Get all public taxonomies
$public_taxonomies = get_taxonomies( array( 'public' => true ), 'objects' );

// Get taxonomies for posts
$post_taxonomies = get_object_taxonomies( 'post', 'objects' );

get_object_taxonomies()

Returns taxonomies registered for the requested object or object type.

get_object_taxonomies( string|string[]|WP_Post $object_type, string $output = 'names' ): string[]|WP_Taxonomy[]

Returns: Array of taxonomy names or objects.

taxonomy_exists()

Determines whether the taxonomy name exists.

taxonomy_exists( string $taxonomy ): bool

Returns: true if exists, false otherwise.

is_taxonomy_hierarchical()

Determines whether the taxonomy object is hierarchical.

is_taxonomy_hierarchical( string $taxonomy ): bool

Returns: true if hierarchical, false if not or taxonomy doesn’t exist.

is_taxonomy_viewable()

Determines whether a taxonomy is considered "viewable".

is_taxonomy_viewable( string|WP_Taxonomy $taxonomy ): bool

Returns: true if publicly queryable.

get_taxonomy_labels()

Builds an object with all taxonomy labels out of a taxonomy object.

get_taxonomy_labels( WP_Taxonomy $tax ): object

Returns: Object with label properties.

Term Retrieval

get_terms()

Retrieves the terms in a given taxonomy or list of taxonomies.

get_terms( array|string $args = array(), array|string $deprecated = '' ): WP_Term[]|int[]|string[]|string|WP_Error

Returns: Array of terms, count as numeric string, or WP_Error.

Example:

$terms = get_terms( array(
    'taxonomy'   => 'category',
    'hide_empty' => false,
    'orderby'    => 'name',
    'order'      => 'ASC',
) );

get_term()

Gets all term data from database by term ID.

get_term( int|WP_Term|object $term, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' ): WP_Term|array|WP_Error|null

Returns: WP_Term or array on success, WP_Error or null on failure.

get_term_by()

Gets all term data from database by term field and data.

get_term_by( string $field, string|int $value, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' ): WP_Term|array|false

Returns: WP_Term or array on success, false on failure.

Example:

$term = get_term_by( 'slug', 'uncategorized', 'category' );

get_term_children()

Merges all term children into a single array of their IDs.

get_term_children( int $term_id, string $taxonomy ): array|WP_Error

Returns: Array of term IDs or WP_Error.

get_term_field()

Gets sanitized term field.

get_term_field( string $field, int|WP_Term $term, string $taxonomy = '', string $context = 'display' ): string|int|null|WP_Error

Returns: Field value or WP_Error.

term_exists()

Determines whether a taxonomy term exists.

term_exists( int|string $term, string $taxonomy = '', int $parent_term = null ): mixed

Returns: null if not found, term ID if no taxonomy specified, array with term_id and term_taxonomy_id if taxonomy specified.

is_term_publicly_viewable()

Determines if a term is publicly viewable.

is_term_publicly_viewable( int|WP_Term $term ): bool

Returns: true if taxonomy is viewable.

Object-Term Relationships

wp_get_object_terms()

Retrieves the terms associated with the given object(s), in the supplied taxonomies.

wp_get_object_terms( int|int[] $object_ids, string|string[] $taxonomies, array|string $args = array() ): WP_Term[]|int[]|string[]|string|WP_Error

Returns: Array of terms or WP_Error.

Example:

$categories = wp_get_object_terms( $post_id, 'category', array(
    'fields' => 'names',
) );

wp_set_object_terms()

Creates term and taxonomy relationships.

wp_set_object_terms( int $object_id, string|int|array $terms, string $taxonomy, bool $append = false ): array|WP_Error

Returns: Array of term taxonomy IDs or WP_Error.

Example:

// Set categories for a post
wp_set_object_terms( $post_id, array( 'news', 'featured' ), 'category' );

// Add tags without replacing existing
wp_set_object_terms( $post_id, array( 'wordpress', 'tutorial' ), 'post_tag', true );

wp_add_object_terms()

Adds term(s) associated with a given object.

wp_add_object_terms( int $object_id, string|int|array $terms, array|string $taxonomy ): array|WP_Error

Returns: Array of term taxonomy IDs or WP_Error.

wp_remove_object_terms()

Removes term(s) associated with a given object.

wp_remove_object_terms( int $object_id, string|int|array $terms, string $taxonomy ): bool|WP_Error

Returns: true on success, false or WP_Error on failure.

wp_delete_object_term_relationships()

Unlinks the object from the taxonomy or taxonomies.

wp_delete_object_term_relationships( int $object_id, string|array $taxonomies ): void

is_object_in_term()

Determines if the given object is associated with any of the given terms.

is_object_in_term( int $object_id, string $taxonomy, int|string|int[]|string[] $terms = null ): bool|WP_Error

Returns: true/false or WP_Error.

is_object_in_taxonomy()

Determines if the given object type is associated with the given taxonomy.

is_object_in_taxonomy( string $object_type, string $taxonomy ): bool

Returns: true if associated.

get_objects_in_term()

Retrieves object IDs of valid taxonomy and term.

get_objects_in_term( int|int[] $term_ids, string|string[] $taxonomies, array|string $args = array() ): string[]|WP_Error

Returns: Array of object IDs as strings or WP_Error.

Term Modification

wp_insert_term()

Adds a new term to the database.

wp_insert_term( string $term, string $taxonomy, array|string $args = array() ): array|WP_Error

Args

Returns: Array with term_id and term_taxonomy_id or WP_Error.

Error Codes:

• invalid_taxonomy — Taxonomy doesn’t exist
• invalid_term_id — Term ID is 0
• empty_term_name — Empty term name
• missing_parent — Parent term doesn’t exist
• term_exists — Term already exists at this level

Example:

$result = wp_insert_term( 'Jazz', 'genre', array(
    'description' => 'Jazz music genre',
    'slug'        => 'jazz',
    'parent'      => $music_term_id,
) );

if ( ! is_wp_error( $result ) ) {
    $term_id = $result['term_id'];
}

wp_update_term()

Updates term based on arguments provided.

wp_update_term( int $term_id, string $taxonomy, array $args = array() ): array|WP_Error

Returns: Array with term_id and term_taxonomy_id or WP_Error.

wp_delete_term()

Removes a term from the database.

wp_delete_term( int $term, string $taxonomy, array|string $args = array() ): bool|int|WP_Error

Args

Returns: true on success, false if term doesn’t exist, 0 if default category, WP_Error on failure.

wp_delete_category()

Deletes one existing category.

wp_delete_category( int $cat_id ): bool|int|WP_Error

Returns: Same as wp_delete_term().

Term Metadata

add_term_meta()

Adds metadata to a term.

add_term_meta( int $term_id, string $meta_key, mixed $meta_value, bool $unique = false ): int|false|WP_Error

Returns: Meta ID on success, false on failure, WP_Error if term is shared.

get_term_meta()

Retrieves metadata for a term.

get_term_meta( int $term_id, string $key = '', bool $single = false ): mixed

Returns: Meta value(s), empty string/array for non-existing, false for invalid term ID.

update_term_meta()

Updates term metadata.

update_term_meta( int $term_id, string $meta_key, mixed $meta_value, mixed $prev_value = '' ): int|bool|WP_Error

Returns: Meta ID if new, true on update, false on failure/no change, WP_Error if term is shared.

delete_term_meta()

Removes metadata matching criteria from a term.

delete_term_meta( int $term_id, string $meta_key, mixed $meta_value = '' ): bool

Returns: true on success, false on failure.

register_term_meta()

Registers a meta key for terms.

register_term_meta( string $taxonomy, string $meta_key, array $args ): bool

Returns: true on success, false on failure.

unregister_term_meta()

Unregisters a meta key for terms.

unregister_term_meta( string $taxonomy, string $meta_key ): bool

Returns: true on success, false if not registered.

has_term_meta()

Gets all meta data, including meta IDs, for the given term ID.

has_term_meta( int $term_id ): array|false

Returns: Array with meta_key, meta_value, meta_id, term_id or false.

Term Counting

wp_count_terms()

Counts how many terms are in taxonomy.

wp_count_terms( array|string $args = array(), array|string $deprecated = '' ): string|WP_Error

Returns: Numeric string count or WP_Error.

wp_update_term_count()

Updates the amount of terms in taxonomy.

wp_update_term_count( int|array $terms, string $taxonomy, bool $do_deferred = false ): bool

Returns: true on success, false if empty.

wp_defer_term_counting()

Enables or disables term counting.

wp_defer_term_counting( bool $defer = null ): bool

Returns: Whether deferring is enabled.

Term Hierarchy

term_is_ancestor_of()

Checks if a term is an ancestor of another term.

term_is_ancestor_of( int|object $term1, int|object $term2, string $taxonomy ): bool

Returns: true if $term2 is child of $term1.

get_ancestors()

Gets an array of ancestor IDs for a given object.

get_ancestors( int $object_id = 0, string $object_type = '', string $resource_type = '' ): int[]

Returns: Array of ancestor IDs from lowest to highest.

wp_get_term_taxonomy_parent_id()

Returns the term’s parent’s term ID.

wp_get_term_taxonomy_parent_id( int $term_id, string $taxonomy ): int|false

Returns: Parent term ID or false.

Term URLs

get_term_link()

Generates a permalink for a taxonomy term archive.

get_term_link( WP_Term|int|string $term, string $taxonomy = '' ): string|WP_Error

Returns: URL string or WP_Error.

Example:

$category = get_category_by_slug( 'news' );
$link = get_term_link( $category );

Sanitization

sanitize_term()

Sanitizes all term fields.

sanitize_term( array|object $term, string $taxonomy, string $context = 'display' ): array|object

Returns: Term with sanitized fields.

sanitize_term_field()

Sanitizes the field value in the term based on the context.

sanitize_term_field( string $field, string $value, int $term_id, string $taxonomy, string $context ): mixed

Returns: Sanitized field value.

wp_unique_term_slug()

Makes term slug unique, if it isn’t already.

wp_unique_term_slug( string $slug, object $term ): string

Returns: Unique slug.

Caching

clean_term_cache()

Removes all of the term IDs from the cache.

clean_term_cache( int|int[] $ids, string $taxonomy = '', bool $clean_taxonomy = true ): void

clean_object_term_cache()

Removes the taxonomy relationship to terms from the cache.

clean_object_term_cache( int|array $object_ids, array|string $object_type ): void

clean_taxonomy_cache()

Cleans the caches for a taxonomy.

clean_taxonomy_cache( string $taxonomy ): void

get_object_term_cache()

Retrieves the cached term objects for the given object ID.

get_object_term_cache( int $id, string $taxonomy ): bool|WP_Term[]|WP_Error

Returns: Array of WP_Term objects, false if not cached, WP_Error on error.

update_object_term_cache()

Updates the cache for the given term object ID(s).

update_object_term_cache( string|int[] $object_ids, string|string[] $object_type ): void|false

Returns: void on success, false if all already cached.

update_term_cache()

Updates terms in cache.

update_term_cache( WP_Term[] $terms, string $taxonomy = '' ): void

update_termmeta_cache()

Updates metadata cache for list of term IDs.

update_termmeta_cache( array $term_ids ): array|false

Returns: Array of metadata or false if nothing to update.

wp_lazyload_term_meta()

Queue term meta for lazy-loading.

wp_lazyload_term_meta( array $term_ids ): void

Display Functions

the_taxonomies()

Displays the taxonomies of a post with available options.

the_taxonomies( array $args = array() ): void

Args

get_the_taxonomies()

Retrieves all taxonomies associated with a post.

get_the_taxonomies( int|WP_Post $post = 0, array $args = array() ): string[]

Returns: Array of formatted taxonomy strings keyed by taxonomy name.

get_post_taxonomies()

Retrieves all taxonomy names for the given post.

get_post_taxonomies( int|WP_Post $post = 0 ): string[]

Returns: Array of taxonomy names.

Split Terms

wp_get_split_terms()

Gets data about terms that previously shared a single term_id, but have since been split.

wp_get_split_terms( int $old_term_id ): array

Returns: Array of new term IDs, keyed by taxonomy.

wp_get_split_term()

Gets the new term ID corresponding to a previously split term.

wp_get_split_term( int $old_term_id, string $taxonomy ): int|false

Returns: New term ID or false.

wp_term_is_shared()

Determines whether a term is shared between multiple taxonomies.

wp_term_is_shared( int $term_id ): bool

Returns: true if shared, false if not or splitting is finished.