PHPXRef 0.7.1 : WordPress : Detail view of taxonomy.php

Functions that are not part of a class:

Creates the initial taxonomies.

This function fires twice: in wp-settings.php before plugins are loaded (for
backward compatibility reasons), and again on the {@see 'init'} action. We must
avoid registering rewrite rules before the {@see 'init'} action.

since: 2.8.0
since: 5.9.0 Added `'wp_template_part_area'` taxonomy.

get_taxonomies( $args = array() X-Ref

Retrieves a list of registered taxonomy names or objects.

param: array $args Optional. An array of `key => value` arguments to match against the taxonomy objects.
param: string $output Optional. The type of output to return in the array. Accepts either taxonomy 'names'
param: string $operator Optional. The logical operation to perform. Accepts 'and' or 'or'. 'or' means only
return: string[]|WP_Taxonomy[] An array of taxonomy names or objects.
since: 3.0.0

get_object_taxonomies( $object, $output = 'names' ) X-Ref

Returns the names or objects of the taxonomies which are registered for the requested object or object type,
such as a post object or post type name.

Example:

$taxonomies = get_object_taxonomies( 'post' );

This results in:

Array( 'category', 'post_tag' )

param: string|string[]|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
param: string $output Optional. The type of output to return in the array. Accepts either
return: string[]|WP_Taxonomy[] The names or objects of all taxonomies of `$object_type`.
since: 2.3.0

get_taxonomy( $taxonomy ) X-Ref

Retrieves the taxonomy object of $taxonomy.

The get_taxonomy function will first check that the parameter string given
is a taxonomy object and if it is, it will return it.

param: string $taxonomy Name of taxonomy object to return.
return: WP_Taxonomy|false The taxonomy object or false if $taxonomy doesn't exist.
since: 2.3.0

taxonomy_exists( $taxonomy ) X-Ref

Determines whether the taxonomy name exists.

Formerly is_taxonomy(), introduced in 2.3.0.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

param: string $taxonomy Name of taxonomy object.
return: bool Whether the taxonomy exists.
since: 3.0.0

is_taxonomy_hierarchical( $taxonomy ) X-Ref

Determines whether the taxonomy object is hierarchical.

Checks to make sure that the taxonomy is an object first. Then Gets the
object, and finally returns the hierarchical value in the object.

A false return value might also mean that the taxonomy does not exist.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

param: string $taxonomy Name of taxonomy object.
return: bool Whether the taxonomy is hierarchical.
since: 2.3.0

register_taxonomy( $taxonomy, $object_type, $args = array() X-Ref

Creates or modifies a taxonomy object.

Note: Do not use before the {@see 'init'} hook.

A simple function for creating or modifying a taxonomy object based on
the parameters given. If modifying an existing taxonomy object, note
that the `$object_type` value from the original registration will be
overwritten.

param: string $taxonomy Taxonomy key, must not exceed 32 characters.
param: array|string $object_type Object type or array of object types with which the taxonomy should be associated.
param: array|string $args {
return: WP_Taxonomy|WP_Error The registered taxonomy object on success, WP_Error object on failure.
since: 2.3.0
since: 4.2.0 Introduced `show_in_quick_edit` argument.
since: 4.4.0 The `show_ui` argument is now enforced on the term editing screen.
since: 4.4.0 The `public` argument now controls whether the taxonomy can be queried on the front end.
since: 4.5.0 Introduced `publicly_queryable` argument.
since: 4.7.0 Introduced `show_in_rest`, 'rest_base' and 'rest_controller_class'
since: 5.1.0 Introduced `meta_box_sanitize_cb` argument.
since: 5.4.0 Added the registered taxonomy object as a return value.
since: 5.5.0 Introduced `default_term` argument.
since: 5.9.0 Introduced `rest_namespace` argument.

unregister_taxonomy( $taxonomy ) X-Ref

Unregisters a taxonomy.

Can not be used to unregister built-in taxonomies.

param: string $taxonomy Taxonomy name.
return: true|WP_Error True on success, WP_Error on failure or if the taxonomy doesn't exist.
since: 4.5.0

get_taxonomy_labels( $tax ) X-Ref

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

param: WP_Taxonomy $tax Taxonomy object.
return: object {
since: 3.0.0
since: 4.3.0 Added the `no_terms` label.
since: 4.4.0 Added the `items_list_navigation` and `items_list` labels.
since: 4.9.0 Added the `most_used` and `back_to_items` labels.
since: 5.7.0 Added the `filter_by_item` label.
since: 5.8.0 Added the `item_link` and `item_link_description` labels.
since: 5.9.0 Added the `name_field_description`, `slug_field_description`,

register_taxonomy_for_object_type( $taxonomy, $object_type ) X-Ref

Adds an already registered taxonomy to an object type.

param: string $taxonomy Name of taxonomy object.
param: string $object_type Name of the object type.
return: bool True if successful, false if not.
since: 3.0.0

unregister_taxonomy_for_object_type( $taxonomy, $object_type ) X-Ref

Removes an already registered taxonomy from an object type.

param: string $taxonomy Name of taxonomy object.
param: string $object_type Name of the object type.
return: bool True if successful, false if not.
since: 3.7.0

get_objects_in_term( $term_ids, $taxonomies, $args = array() X-Ref

Retrieves object IDs of valid taxonomy and term.

The strings of `$taxonomies` must exist before this function will continue.
On failure of finding a valid taxonomy, it will return a WP_Error.

The `$terms` aren't checked the same as `$taxonomies`, but still need to exist
for object IDs to be returned.

It is possible to change the order that object IDs are returned by using `$args`
with either ASC or DESC array. The value should be in the key named 'order'.

param: int|int[] $term_ids Term ID or array of term IDs of terms that will be used.
param: string|string[] $taxonomies String of taxonomy name or Array of string values of taxonomy names.
param: array|string $args Change the order of the object IDs, either ASC or DESC.
return: string[]|WP_Error An array of object IDs as numeric strings on success,
since: 2.3.0

get_tax_sql( $tax_query, $primary_table, $primary_id_column ) X-Ref

Given a taxonomy query, generates SQL to be appended to a main query.

param: array $tax_query A compact tax query
param: string $primary_table
param: string $primary_id_column
return: string[]
since: 3.1.0

get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) X-Ref

Gets all term data from database by term ID.

The usage of the get_term function is to apply filters to a term object. It
is possible to get a term object from the database before applying the
filters.

$term ID must be part of $taxonomy, to get from the database. Failure, might
be able to be captured by the hooks. Failure would be the same value as $wpdb
returns for the get_row method.

There are two hooks, one is specifically for each term, named 'get_term', and
the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the
term object, and the taxonomy name as parameters. Both hooks are expected to
return a term object.

{@see 'get_term'} hook - Takes two parameters the term Object and the taxonomy name.
Must return term object. Used in get_term() as a catch-all filter for every
$term.

{@see 'get_$taxonomy'} hook - Takes two parameters the term Object and the taxonomy
name. Must return term object. $taxonomy will be the taxonomy name, so for
example, if 'category', it would be 'get_category' as the filter name. Useful
for custom taxonomies or plugging into default taxonomies.

param: int|WP_Term|object $term     If integer, term data will be fetched from the database,
param: string             $taxonomy Optional. Taxonomy name that `$term` is part of.
param: string             $output   Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
param: string             $filter   Optional. How to sanitize term fields. Default 'raw'.
return: WP_Term|array|WP_Error|null WP_Term instance (or array) on success, depending on the `$output` value.
since: 2.3.0
since: 4.4.0 Converted to return a WP_Term object if `$output` is `OBJECT`.

get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) X-Ref

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

Warning: $value is not escaped for 'name' $field. You must do it yourself, if
required.

The default $field is 'id', therefore it is possible to also use null for
field, but not recommended that you do so.

If $value does not exist, the return value will be false. If $taxonomy exists
and $field and $value combinations exist, the term will be returned.

This function will always return the first term that matches the `$field`-
`$value`-`$taxonomy` combination specified in the parameters. If your query
is likely to match more than one term (as is likely to be the case when
`$field` is 'name', for example), consider using get_terms() instead; that
way, you will get all matching terms, and can provide your own logic for
deciding which one was intended.

param: string     $field    Either 'slug', 'name', 'term_id' (or 'id', 'ID'), or 'term_taxonomy_id'.
param: string|int $value    Search for this term value.
param: string     $taxonomy Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'.
param: string     $output   Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
param: string     $filter   Optional. How to sanitize term fields. Default 'raw'.
return: WP_Term|array|false WP_Term instance (or array) on success, depending on the `$output` value.
since: 2.3.0
since: 4.4.0 `$taxonomy` is optional if `$field` is 'term_taxonomy_id'. Converted to return
since: 5.5.0 Added 'ID' as an alias of 'id' for the `$field` parameter.

get_term_children( $term_id, $taxonomy ) X-Ref

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

This recursive function will merge all of the children of $term into the same
array of term IDs. Only useful for taxonomies which are hierarchical.

Will return an empty array if $term does not exist in $taxonomy.

param: int $term_id ID of term to get children.
param: string $taxonomy Taxonomy name.
return: array|WP_Error List of term IDs. WP_Error returned if `$taxonomy` does not exist.
since: 2.3.0

get_term_field( $field, $term, $taxonomy = '', $context = 'display' ) X-Ref

Gets sanitized term field.

The function is for contextual reasons and for simplicity of usage.

param: string      $field    Term field to fetch.
param: int|WP_Term $term     Term ID or object.
param: string      $taxonomy Optional. Taxonomy name. Default empty.
param: string      $context  Optional. How to sanitize term fields. Look at sanitize_term_field() for available options.
return: string|int|null|WP_Error Will return an empty string if $term is not an object or if $field is not set in $term.
since: 2.3.0
since: 4.4.0 The `$taxonomy` parameter was made optional. `$term` can also now accept a WP_Term object.

get_term_to_edit( $id, $taxonomy ) X-Ref

Sanitizes term for editing.

Return value is sanitize_term() and usage is for sanitizing the term for
editing. Function is for contextual and simplicity.

param: int|object $id Term ID or object.
param: string $taxonomy Taxonomy name.
return: string|int|null|WP_Error Will return empty string if $term is not an object.
since: 2.3.0

get_terms( $args = array() X-Ref

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

You can fully inject any customizations to the query before it is sent, as
well as control the output with a filter.

The return type varies depending on the value passed to `$args['fields']`. See
WP_Term_Query::get_terms() for details. In all cases, a `WP_Error` object will
be returned if an invalid taxonomy is requested.

The {@see 'get_terms'} filter will be called when the cache has the term and will
pass the found term along with the array of $taxonomies and array of $args.
This filter is also called before the array of terms is passed and will pass
the array of terms, along with the $taxonomies and $args.

The {@see 'list_terms_exclusions'} filter passes the compiled exclusions along with
the $args.

The {@see 'get_terms_orderby'} filter passes the `ORDER BY` clause for the query
along with the $args array.

Prior to 4.5.0, the first parameter of `get_terms()` was a taxonomy or list of taxonomies:

$terms = get_terms( 'post_tag', array(
'hide_empty' => false,
) );

Since 4.5.0, taxonomies should be passed via the 'taxonomy' argument in the `$args` array:

$terms = get_terms( array(
'taxonomy' => 'post_tag',
'hide_empty' => false,
) );

param: array|string $args Optional. Array or string of arguments. See WP_Term_Query::__construct()
param: array|string $deprecated Optional. Argument array, when using the legacy function parameter format.
return: WP_Term[]|int[]|string[]|string|WP_Error Array of terms, a count thereof as a numeric string,
since: 2.3.0
since: 4.2.0 Introduced 'name' and 'childless' parameters.
since: 4.4.0 Introduced the ability to pass 'term_id' as an alias of 'id' for the `orderby` parameter.
since: 4.5.0 Changed the function signature so that the `$args` array can be provided as the first parameter.
since: 4.8.0 Introduced 'suppress_filter' parameter.

add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) X-Ref

Adds metadata to a term.

param: int    $term_id    Term ID.
param: string $meta_key   Metadata name.
param: mixed  $meta_value Metadata value. Must be serializable if non-scalar.
param: bool   $unique     Optional. Whether the same key should not be added.
return: int|false|WP_Error Meta ID on success, false on failure.
since: 4.4.0

delete_term_meta( $term_id, $meta_key, $meta_value = '' ) X-Ref

Removes metadata matching criteria from a term.

param: int    $term_id    Term ID.
param: string $meta_key   Metadata name.
param: mixed  $meta_value Optional. Metadata value. If provided,
return: bool True on success, false on failure.
since: 4.4.0

get_term_meta( $term_id, $key = '', $single = false ) X-Ref

Retrieves metadata for a term.

param: int    $term_id Term ID.
param: string $key     Optional. The meta key to retrieve. By default,
param: bool   $single  Optional. Whether to return a single value.
return: mixed An array of values if `$single` is false.
since: 4.4.0

update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' ) X-Ref

Updates term metadata.

Use the `$prev_value` parameter to differentiate between meta fields with the same key and term ID.

If the meta field for the term does not exist, it will be added.

param: int    $term_id    Term ID.
param: string $meta_key   Metadata key.
param: mixed  $meta_value Metadata value. Must be serializable if non-scalar.
param: mixed  $prev_value Optional. Previous value to check before updating.
return: int|bool|WP_Error Meta ID if the key didn't exist. true on successful update,
since: 4.4.0

update_termmeta_cache( $term_ids ) X-Ref

Updates metadata cache for list of term IDs.

Performs SQL query to retrieve all metadata for the terms matching `$term_ids` and stores them in the cache.
Subsequent calls to `get_term_meta()` will not need to query the database.

param: array $term_ids List of term IDs.
return: array|false An array of metadata on success, false if there is nothing to update.
since: 4.4.0

has_term_meta( $term_id ) X-Ref

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

param: int $term_id Term ID.
return: array|false Array with meta data, or false when the meta table is not installed.
since: 4.9.0

register_term_meta( $taxonomy, $meta_key, array $args ) X-Ref

Registers a meta key for terms.

param: string $taxonomy Taxonomy to register a meta key for. Pass an empty string
param: string $meta_key The meta key to register.
param: array $args Data used to describe the meta key when registered. See
return: bool True if the meta key was successfully registered, false if not.
since: 4.9.8

unregister_term_meta( $taxonomy, $meta_key ) X-Ref

Unregisters a meta key for terms.

param: string $taxonomy Taxonomy the meta key is currently registered for. Pass
param: string $meta_key The meta key to unregister.
return: bool True on success, false if the meta key was not previously registered.
since: 4.9.8

term_exists( $term, $taxonomy = '', $parent = null ) X-Ref

Determines whether a taxonomy term exists.

Formerly is_term(), introduced in 2.3.0.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

param: int|string $term     The term to check. Accepts term ID, slug, or name.
param: string     $taxonomy Optional. The taxonomy name to use.
param: int        $parent   Optional. ID of parent term under which to confine the exists search.
return: mixed Returns null if the term does not exist.
since: 3.0.0
since: 6.0.0 Converted to use `get_terms()`.

term_is_ancestor_of( $term1, $term2, $taxonomy ) X-Ref

Checks if a term is an ancestor of another term.

You can use either an ID or the term object for both parameters.

param: int|object $term1    ID or object to check if this is the parent term.
param: int|object $term2    The child term.
param: string     $taxonomy Taxonomy name that $term1 and `$term2` belong to.
return: bool Whether `$term2` is a child of `$term1`.
since: 3.4.0

sanitize_term( $term, $taxonomy, $context = 'display' ) X-Ref

Sanitizes all term fields.

Relies on sanitize_term_field() to sanitize the term. The difference is that
this function will sanitize **all** fields. The context is based
on sanitize_term_field().

The `$term` is expected to be either an array or an object.

param: array|object $term     The term to check.
param: string       $taxonomy The taxonomy name to use.
param: string       $context  Optional. Context in which to sanitize the term.
return: array|object Term with all fields sanitized.
since: 2.3.0

sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) X-Ref

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

Passing a term field value through the function should be assumed to have
cleansed the value for whatever context the term field is going to be used.

If no context or an unsupported context is given, then default filters will
be applied.

There are enough filters for each context to support a custom filtering
without creating your own filter function. Simply create a function that
hooks into the filter you need.

param: string $field    Term field to sanitize.
param: string $value    Search for this term value.
param: int    $term_id  Term ID.
param: string $taxonomy Taxonomy name.
param: string $context  Context in which to sanitize the term field.
return: mixed Sanitized field.
since: 2.3.0

wp_count_terms( $args = array() X-Ref

Counts how many terms are in taxonomy.

Default $args is 'hide_empty' which can be 'hide_empty=true' or array('hide_empty' => true).

param: array|string $args Optional. Array of arguments that get passed to get_terms().
param: array|string $deprecated Optional. Argument array, when using the legacy function parameter format.
return: string|WP_Error Numeric string containing the number of terms in that
since: 2.3.0
since: 5.6.0 Changed the function signature so that the `$args` array can be provided as the first parameter.

wp_delete_object_term_relationships( $object_id, $taxonomies ) X-Ref

Unlinks the object from the taxonomy or taxonomies.

Will remove all relationships between the object and any terms in
a particular taxonomy or taxonomies. Does not remove the term or
taxonomy itself.

param: int $object_id The term object ID that refers to the term.
param: string|array $taxonomies List of taxonomy names or single taxonomy name.
since: 2.3.0

wp_delete_term( $term, $taxonomy, $args = array() X-Ref

Removes a term from the database.

If the term is a parent of other terms, then the children will be updated to
that term's parent.

Metadata associated with the term will be deleted.

param: int $term Term ID.
param: string $taxonomy Taxonomy name.
param: array|string $args {
return: bool|int|WP_Error True on success, false if term does not exist. Zero on attempted
since: 2.3.0

wp_delete_category( $cat_ID ) X-Ref

Deletes one existing category.

param: int $cat_ID Category term ID.
return: bool|int|WP_Error Returns true if completes delete action; false if term doesn't exist;
since: 2.0.0

wp_get_object_terms( $object_ids, $taxonomies, $args = array() X-Ref

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

param: int|int[] $object_ids The ID(s) of the object(s) to retrieve.
param: string|string[] $taxonomies The taxonomy names to retrieve terms from.
param: array|string $args See WP_Term_Query::__construct() for supported arguments.
return: WP_Term[]|WP_Error Array of terms or empty array if no terms found.
since: 2.3.0
since: 4.2.0 Added support for 'taxonomy', 'parent', and 'term_taxonomy_id' values of `$orderby`.
since: 4.4.0 Introduced `$meta_query` and `$update_term_meta_cache` arguments. When `$fields` is 'all' or
since: 4.7.0 Refactored to use WP_Term_Query, and to support any WP_Term_Query arguments.

wp_insert_term( $term, $taxonomy, $args = array() X-Ref

Adds a new term to the database.

A non-existent term is inserted in the following sequence:
1. The term is added to the term table, then related to the taxonomy.
2. If everything is correct, several actions are fired.
3. The 'term_id_filter' is evaluated.
4. The term cache is cleaned.
5. Several more actions are fired.
6. An array is returned containing the `term_id` and `term_taxonomy_id`.

If the 'slug' argument is not empty, then it is checked to see if the term
is invalid. If it is not a valid, existing term, it is added and the term_id
is given.

If the taxonomy is hierarchical, and the 'parent' argument is not empty,
the term is inserted and the term_id will be given.

Error handling:
If `$taxonomy` does not exist or `$term` is empty,
a WP_Error object will be returned.

If the term already exists on the same hierarchical level,
or the term slug and name are not unique, a WP_Error object will be returned.

param: string $term The term name to add.
param: string $taxonomy The taxonomy to which to add the term.
param: array|string $args {
return: array|WP_Error {
since: 2.3.0

wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) X-Ref

Creates term and taxonomy relationships.

Relates an object (post, link, etc.) to a term and taxonomy type. Creates the
term and taxonomy relationship if it doesn't already exist. Creates a term if
it doesn't exist (using the slug).

A relationship means that the term is grouped in or belongs to the taxonomy.
A term has no meaning until it is given context by defining which taxonomy it
exists under.

param: int              $object_id The object to relate to.
param: string|int|array $terms     A single term slug, single term ID, or array of either term slugs or IDs.
param: string           $taxonomy  The context in which to relate the term to the object.
param: bool             $append    Optional. If false will delete difference of terms. Default false.
return: array|WP_Error Term taxonomy IDs of the affected terms or WP_Error on failure.
since: 2.3.0

wp_add_object_terms( $object_id, $terms, $taxonomy ) X-Ref

Adds term(s) associated with a given object.

param: int              $object_id The ID of the object to which the terms will be added.
param: string|int|array $terms     The slug(s) or ID(s) of the term(s) to add.
param: array|string     $taxonomy  Taxonomy name.
return: array|WP_Error Term taxonomy IDs of the affected terms.
since: 3.6.0

wp_remove_object_terms( $object_id, $terms, $taxonomy ) X-Ref

Removes term(s) associated with a given object.

param: int              $object_id The ID of the object from which the terms will be removed.
param: string|int|array $terms     The slug(s) or ID(s) of the term(s) to remove.
param: string           $taxonomy  Taxonomy name.
return: bool|WP_Error True on success, false or WP_Error on failure.
since: 3.6.0

wp_unique_term_slug( $slug, $term ) X-Ref

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

The `$slug` has to be unique global to every taxonomy, meaning that one
taxonomy term can't have a matching slug with another taxonomy term. Each
slug has to be globally unique for every taxonomy.

The way this works is that if the taxonomy that the term belongs to is
hierarchical and has a parent, it will append that parent to the $slug.

If that still doesn't return a unique slug, then it tries to append a number
until it finds a number that is truly unique.

The only purpose for `$term` is for appending a parent, if one exists.

param: string $slug The string that will be tried for a unique slug.
param: object $term The term object that the `$slug` will belong to.
return: string Will return a true unique slug.
since: 2.3.0

wp_update_term( $term_id, $taxonomy, $args = array() X-Ref

Updates term based on arguments provided.

The `$args` will indiscriminately override all values with the same field name.
Care must be taken to not override important information need to update or
update will fail (or perhaps create a new term, neither would be acceptable).

Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not
defined in `$args` already.

'alias_of' will create a term group, if it doesn't already exist, and
update it for the `$term`.

If the 'slug' argument in `$args` is missing, then the 'name' will be used.
If you set 'slug' and it isn't unique, then a WP_Error is returned.
If you don't pass any slug, then a unique one will be created.

param: int $term_id The ID of the term.
param: string $taxonomy The taxonomy of the term.
param: array|string $args {
return: array|WP_Error An array containing the `term_id` and `term_taxonomy_id`,
since: 2.3.0

wp_defer_term_counting( $defer = null ) X-Ref

Enables or disables term counting.

param: bool $defer Optional. Enable if true, disable if false.
return: bool Whether term counting is enabled or disabled.
since: 2.5.0

wp_update_term_count( $terms, $taxonomy, $do_deferred = false ) X-Ref

Updates the amount of terms in taxonomy.

If there is a taxonomy callback applied, then it will be called for updating
the count.

The default action is to count what the amount of terms have the relationship
of term ID. Once that is done, then update the database.

param: int|array $terms       The term_taxonomy_id of the terms.
param: string    $taxonomy    The context of the term.
param: bool      $do_deferred Whether to flush the deferred term counts too. Default false.
return: bool If no terms will return false, and if successful will return true.
since: 2.3.0

wp_update_term_count_now( $terms, $taxonomy ) X-Ref

Performs term count update immediately.

param: array $terms The term_taxonomy_id of terms to update.
param: string $taxonomy The context of the term.
return: true Always true when complete.
since: 2.5.0

clean_object_term_cache( $object_ids, $object_type ) X-Ref

Removes the taxonomy relationship to terms from the cache.

Will remove the entire taxonomy relationship containing term `$object_id`. The
term IDs have to exist within the taxonomy `$object_type` for the deletion to
take place.

param: int|array $object_ids Single or list of term object ID(s).
param: array|string $object_type The taxonomy object type.
since: 2.3.0

clean_term_cache( $ids, $taxonomy = '', $clean_taxonomy = true ) X-Ref

Removes all of the term IDs from the cache.

param: int|int[] $ids            Single or array of term IDs.
param: string    $taxonomy       Optional. Taxonomy slug. Can be empty, in which case the taxonomies of the passed
param: bool      $clean_taxonomy Optional. Whether to clean taxonomy wide caches (true), or just individual
since: 2.3.0

clean_taxonomy_cache( $taxonomy ) X-Ref

Cleans the caches for a taxonomy.

param: string $taxonomy Taxonomy slug.
since: 4.9.0

get_object_term_cache( $id, $taxonomy ) X-Ref

Retrieves the cached term objects for the given object ID.

Upstream functions (like get_the_terms() and is_object_in_term()) are
responsible for populating the object-term relationship cache. The current
function only fetches relationship data that is already in the cache.

param: int $id Term object ID, for example a post, comment, or user ID.
param: string $taxonomy Taxonomy name.
return: bool|WP_Term[]|WP_Error Array of `WP_Term` objects, if cached.
since: 2.3.0
since: 4.7.0 Returns a `WP_Error` object if there's an error with

update_object_term_cache( $object_ids, $object_type ) X-Ref

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

Note: Due to performance concerns, great care should be taken to only update
term caches when necessary. Processing time can increase exponentially depending
on both the number of passed term IDs and the number of taxonomies those terms
belong to.

Caches will only be updated for terms not already cached.

param: string|int[] $object_ids Comma-separated list or array of term object IDs.
param: string|string[] $object_type The taxonomy object type or array of the same.
return: void|false Void on success or if the `$object_ids` parameter is empty,
since: 2.3.0

update_term_cache( $terms, $taxonomy = '' ) X-Ref

Updates terms in cache.

param: WP_Term[] $terms Array of term objects to change.
param: string $taxonomy Not used.
since: 2.3.0

_get_term_hierarchy( $taxonomy ) X-Ref

Retrieves children of taxonomy as term IDs.

param: string $taxonomy Taxonomy name.
return: array Empty if $taxonomy isn't hierarchical or returns children as term IDs.
since: 2.3.0

_get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array() X-Ref

Gets the subset of $terms that are descendants of $term_id.

If `$terms` is an array of objects, then _get_term_children() returns an array of objects.
If `$terms` is an array of IDs, then _get_term_children() returns an array of IDs.

param: int    $term_id   The ancestor term: all returned terms should be descendants of `$term_id`.
param: array  $terms     The set of terms - either an array of term objects or term IDs - from which those that
param: string $taxonomy  The taxonomy which determines the hierarchy of the terms.
param: array  $ancestors Optional. Term ancestors that have already been identified. Passed by reference, to keep
return: array|WP_Error The subset of $terms that are descendants of $term_id.
since: 2.3.0

_pad_term_counts( &$terms, $taxonomy ) X-Ref

Adds count of children to parent count.

Recalculates term counts by including items from child terms. Assumes all
relevant children are already in the $terms argument.

param: object[]|WP_Term[] $terms List of term objects (passed by reference).
param: string $taxonomy Term context.
since: 2.3.0

_prime_term_caches( $term_ids, $update_meta_cache = true ) X-Ref

Adds any terms from the given IDs to the cache that do not already exist in cache.

param: array $term_ids Array of term IDs.
param: bool $update_meta_cache Optional. Whether to update the meta cache. Default true.
since: 4.6.0

_update_post_term_count( $terms, $taxonomy ) X-Ref

Updates term count based on object types of the current taxonomy.

Private function for the default callback for post_tag and category
taxonomies.

param: int[] $terms List of term taxonomy IDs.
param: WP_Taxonomy $taxonomy Current taxonomy object of terms.
since: 2.3.0

_update_generic_term_count( $terms, $taxonomy ) X-Ref

Updates term count based on number of objects.

Default callback for the 'link_category' taxonomy.

param: int[] $terms List of term taxonomy IDs.
param: WP_Taxonomy $taxonomy Current taxonomy object of terms.
since: 3.3.0

_split_shared_term( $term_id, $term_taxonomy_id, $record = true ) X-Ref

Creates a new term for a term_taxonomy item that currently shares its term
with another term_taxonomy.

param: int|object $term_id ID of the shared term, or the shared term object.
param: int|object $term_taxonomy_id ID of the term_taxonomy item to receive a new term, or the term_taxonomy object
param: bool $record Whether to record data about the split term in the options table. The recording
return: int|WP_Error When the current term does not need to be split (or cannot be split on the current
since: 4.2.0
since: 4.3.0 Introduced `$record` parameter. Also, `$term_id` and

_wp_batch_split_terms() X-Ref

Splits a batch of shared taxonomy terms.

since: 4.3.0

_wp_check_for_scheduled_split_terms() X-Ref

In order to avoid the _wp_batch_split_terms() job being accidentally removed,
checks that it's still scheduled while we haven't finished splitting terms.

since: 4.3.0

_wp_check_split_default_terms( $term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) X-Ref

Checks default categories when a term gets split to see if any of them need to be updated.

param: int    $term_id          ID of the formerly shared term.
param: int    $new_term_id      ID of the new term created for the $term_taxonomy_id.
param: int    $term_taxonomy_id ID for the term_taxonomy row affected by the split.
param: string $taxonomy         Taxonomy for the split term.
since: 4.2.0

_wp_check_split_terms_in_menus( $term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) X-Ref

Checks menu items when a term gets split to see if any of them need to be updated.

param: int    $term_id          ID of the formerly shared term.
param: int    $new_term_id      ID of the new term created for the $term_taxonomy_id.
param: int    $term_taxonomy_id ID for the term_taxonomy row affected by the split.
param: string $taxonomy         Taxonomy for the split term.
since: 4.2.0

_wp_check_split_nav_menu_terms( $term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) X-Ref

If the term being split is a nav_menu, changes associations.

param: int    $term_id          ID of the formerly shared term.
param: int    $new_term_id      ID of the new term created for the $term_taxonomy_id.
param: int    $term_taxonomy_id ID for the term_taxonomy row affected by the split.
param: string $taxonomy         Taxonomy for the split term.
since: 4.3.0

wp_get_split_terms( $old_term_id ) X-Ref

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

param: int $old_term_id Term ID. This is the old, pre-split term ID.
return: array Array of new term IDs, keyed by taxonomy.
since: 4.2.0

wp_get_split_term( $old_term_id, $taxonomy ) X-Ref

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

param: int $old_term_id Term ID. This is the old, pre-split term ID.
param: string $taxonomy Taxonomy that the term belongs to.
return: int|false If a previously split term is found corresponding to the old term_id and taxonomy,
since: 4.2.0

wp_term_is_shared( $term_id ) X-Ref

Determines whether a term is shared between multiple taxonomies.

Shared taxonomy terms began to be split in 4.3, but failed cron tasks or
other delays in upgrade routines may cause shared terms to remain.

param: int $term_id Term ID.
return: bool Returns false if a term is not shared between multiple taxonomies or
since: 4.4.0

get_term_link( $term, $taxonomy = '' ) X-Ref

Generates a permalink for a taxonomy term archive.

param: WP_Term|int|string $term The term object, ID, or slug whose link will be retrieved.
param: string $taxonomy Optional. Taxonomy. Default empty.
return: string|WP_Error URL of the taxonomy term archive on success, WP_Error if term does not exist.
since: 2.5.0

the_taxonomies( $args = array() X-Ref

Displays the taxonomies of a post with available options.

This function can be used within the loop to display the taxonomies for a
post without specifying the Post ID. You can also use it outside the Loop to
display the taxonomies for a specific post.

param: array $args {
since: 2.5.0

get_the_taxonomies( $post = 0, $args = array() X-Ref

Retrieves all taxonomies associated with a post.

This function can be used within the loop. It will also return an array of
the taxonomies with links to the taxonomy and name.

param: int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
param: array $args {
return: array List of taxonomies.
since: 2.5.0

get_post_taxonomies( $post = 0 ) X-Ref

Retrieves all taxonomy names for the given post.

param: int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
return: string[] An array of all taxonomy names for the given post.
since: 2.5.0

is_object_in_term( $object_id, $taxonomy, $terms = null ) X-Ref

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

The given terms are checked against the object's terms' term_ids, names and slugs.
Terms given as integers will only be checked against the object's terms' term_ids.
If no terms are given, determines if object is associated with any terms in the given taxonomy.

param: int                       $object_id ID of the object (post ID, link ID, ...).
param: string                    $taxonomy  Single taxonomy name.
param: int|string|int[]|string[] $terms     Optional. Term ID, name, slug, or array of such
return: bool|WP_Error WP_Error on input error.
since: 2.7.0

is_object_in_taxonomy( $object_type, $taxonomy ) X-Ref

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

param: string $object_type Object type string.
param: string $taxonomy Single taxonomy name.
return: bool True if object is associated with the taxonomy, otherwise false.
since: 3.0.0

get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' ) X-Ref

Gets an array of ancestor IDs for a given object.

param: int $object_id Optional. The ID of the object. Default 0.
param: string $object_type Optional. The type of object for which we'll be retrieving
param: string $resource_type Optional. Type of resource $object_type is. Accepts 'post_type'
return: int[] An array of IDs of ancestors from lowest to highest in the hierarchy.
since: 3.1.0
since: 4.1.0 Introduced the `$resource_type` argument.

wp_get_term_taxonomy_parent_id( $term_id, $taxonomy ) X-Ref

Returns the term's parent's term ID.

param: int $term_id Term ID.
param: string $taxonomy Taxonomy name.
return: int|false Parent term ID on success, false on failure.
since: 3.1.0

wp_check_term_hierarchy_for_loops( $parent, $term_id, $taxonomy ) X-Ref

Checks the given subset of the term hierarchy for hierarchy loops.
Prevents loops from forming and breaks those that it finds.

Attached to the {@see 'wp_update_term_parent'} filter.

param: int $parent `term_id` of the parent for the term we're checking.
param: int $term_id The term we're checking.
param: string $taxonomy The taxonomy of the term we're checking.
return: int The new parent for the term.
since: 3.1.0

is_taxonomy_viewable( $taxonomy ) X-Ref

Determines whether a taxonomy is considered "viewable".

param: string|WP_Taxonomy $taxonomy Taxonomy name or object.
return: bool Whether the taxonomy should be considered viewable.
since: 5.1.0

wp_cache_set_terms_last_changed() X-Ref

Sets the last changed time for the 'terms' cache group.

since: 5.0.0

wp_check_term_meta_support_prefilter( $check ) X-Ref

Aborts calls to term meta if it is not supported.

param: mixed $check Skip-value for whether to proceed term meta function execution.
return: mixed Original value of $check, or false if term meta is not supported.
since: 5.0.0

File Size:	4989 lines (169 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of WordPress

/wp-includes/ -> taxonomy.php (summary)

Defines 78 functions