[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

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

Core Taxonomy API

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

Defines 78 functions

  create_initial_taxonomies()
  get_taxonomies()
  get_object_taxonomies()
  get_taxonomy()
  taxonomy_exists()
  is_taxonomy_hierarchical()
  register_taxonomy()
  unregister_taxonomy()
  get_taxonomy_labels()
  register_taxonomy_for_object_type()
  unregister_taxonomy_for_object_type()
  get_objects_in_term()
  get_tax_sql()
  get_term()
  get_term_by()
  get_term_children()
  get_term_field()
  get_term_to_edit()
  get_terms()
  add_term_meta()
  delete_term_meta()
  get_term_meta()
  update_term_meta()
  update_termmeta_cache()
  has_term_meta()
  register_term_meta()
  unregister_term_meta()
  term_exists()
  term_is_ancestor_of()
  sanitize_term()
  sanitize_term_field()
  wp_count_terms()
  wp_delete_object_term_relationships()
  wp_delete_term()
  wp_delete_category()
  wp_get_object_terms()
  wp_insert_term()
  wp_set_object_terms()
  wp_add_object_terms()
  wp_remove_object_terms()
  wp_unique_term_slug()
  wp_update_term()
  wp_defer_term_counting()
  wp_update_term_count()
  wp_update_term_count_now()
  clean_object_term_cache()
  clean_term_cache()
  clean_taxonomy_cache()
  get_object_term_cache()
  update_object_term_cache()
  update_term_cache()
  _get_term_hierarchy()
  _get_term_children()
  _pad_term_counts()
  _prime_term_caches()
  _update_post_term_count()
  _update_generic_term_count()
  _split_shared_term()
  _wp_batch_split_terms()
  _wp_check_for_scheduled_split_terms()
  _wp_check_split_default_terms()
  _wp_check_split_terms_in_menus()
  _wp_check_split_nav_menu_terms()
  wp_get_split_terms()
  wp_get_split_term()
  wp_term_is_shared()
  get_term_link()
  the_taxonomies()
  get_the_taxonomies()
  get_post_taxonomies()
  is_object_in_term()
  is_object_in_taxonomy()
  get_ancestors()
  wp_get_term_taxonomy_parent_id()
  wp_check_term_hierarchy_for_loops()
  is_taxonomy_viewable()
  wp_cache_set_terms_last_changed()
  wp_check_term_meta_support_prefilter()

Functions
Functions that are not part of a class:

create_initial_taxonomies()   X-Ref
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.

since: 3.0.0
return: string[]|WP_Taxonomy[] An array of 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

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' )

since: 2.3.0
return: string[]|WP_Taxonomy[] The names or objects of all taxonomies of `$object_type`.
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

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.

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

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.

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

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.

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

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.

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.
return: WP_Taxonomy|WP_Error The registered taxonomy object on success, WP_Error object on failure.
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        {

unregister_taxonomy( $taxonomy )   X-Ref
Unregisters a taxonomy.

Can not be used to unregister built-in taxonomies.

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

get_taxonomy_labels( $tax )   X-Ref
Builds an object with all taxonomy labels out of a taxonomy 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`,
return: object {
param: WP_Taxonomy $tax Taxonomy object.

register_taxonomy_for_object_type( $taxonomy, $object_type )   X-Ref
Adds an already registered taxonomy to an object type.

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

unregister_taxonomy_for_object_type( $taxonomy, $object_type )   X-Ref
Removes an already registered taxonomy from an object type.

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

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'.

since: 2.3.0
return: string[]|WP_Error An array of object IDs as numeric strings on success,
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.

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.

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

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.

since: 2.3.0
since: 4.4.0 Converted to return a WP_Term object if `$output` is `OBJECT`.
return: WP_Term|array|WP_Error|null WP_Term instance (or array) on success, depending on the `$output` value.
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'.

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.

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.
return: WP_Term|array|false WP_Term instance (or array) on success, depending on the `$output` value.
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'.

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.

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

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.

since: 2.3.0
since: 4.4.0 The `$taxonomy` parameter was made optional. `$term` can also now accept a WP_Term object.
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.
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.

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.

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

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,
) );

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.
return: WP_Term[]|int[]|string[]|string|WP_Error Array of terms, a count thereof as a numeric string,
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.

add_term_meta( $term_id, $meta_key, $meta_value, $unique = false )   X-Ref
Adds metadata to a term.

since: 4.4.0
return: int|false|WP_Error Meta ID on success, false on failure.
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.

delete_term_meta( $term_id, $meta_key, $meta_value = '' )   X-Ref
Removes metadata matching criteria from a term.

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

get_term_meta( $term_id, $key = '', $single = false )   X-Ref
Retrieves metadata for a term.

since: 4.4.0
return: mixed An array of values if `$single` is false.
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.

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.

since: 4.4.0
return: int|bool|WP_Error Meta ID if the key didn't exist. true on successful update,
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.

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.

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

has_term_meta( $term_id )   X-Ref
Gets all meta data, including meta IDs, for the given term ID.

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

register_term_meta( $taxonomy, $meta_key, array $args )   X-Ref
Registers a meta key for terms.

since: 4.9.8
return: bool True if the meta key was successfully registered, false if not.
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

unregister_term_meta( $taxonomy, $meta_key )   X-Ref
Unregisters a meta key for terms.

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

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.

since: 3.0.0
since: 6.0.0 Converted to use `get_terms()`.
return: mixed Returns null if the term does not exist.
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.

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.

since: 3.4.0
return: bool Whether `$term2` is a child of `$term1`.
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.

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.

since: 2.3.0
return: array|object Term with all fields sanitized.
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.

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.

since: 2.3.0
return: mixed Sanitized field.
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.

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).

since: 2.3.0
since: 5.6.0 Changed the function signature so that the `$args` array can be provided as the first parameter.
return: string|WP_Error Numeric string containing the number of terms in that
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.

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.

since: 2.3.0
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.

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.

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

wp_delete_category( $cat_ID )   X-Ref
Deletes one existing category.

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

wp_get_object_terms( $object_ids, $taxonomies, $args = array()   X-Ref
Retrieves the terms associated with the given object(s), in the supplied taxonomies.

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.
return: WP_Term[]|WP_Error Array of terms or empty array if no terms found.
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.

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.

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

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.

since: 2.3.0
return: array|WP_Error Term taxonomy IDs of the affected terms or WP_Error on failure.
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.

wp_add_object_terms( $object_id, $terms, $taxonomy )   X-Ref
Adds term(s) associated with a given object.

since: 3.6.0
return: array|WP_Error Term taxonomy IDs of the affected terms.
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.

wp_remove_object_terms( $object_id, $terms, $taxonomy )   X-Ref
Removes term(s) associated with a given object.

since: 3.6.0
return: bool|WP_Error True on success, false or WP_Error on failure.
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.

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.

since: 2.3.0
return: string Will return a true unique slug.
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.

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.

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

wp_defer_term_counting( $defer = null )   X-Ref
Enables or disables term counting.

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

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.

since: 2.3.0
return: bool If no terms will return false, and if successful will return true.
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.

wp_update_term_count_now( $terms, $taxonomy )   X-Ref
Performs term count update immediately.

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

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.

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

clean_term_cache( $ids, $taxonomy = '', $clean_taxonomy = true )   X-Ref
Removes all of the term IDs from the cache.

since: 2.3.0
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

clean_taxonomy_cache( $taxonomy )   X-Ref
Cleans the caches for a taxonomy.

since: 4.9.0
param: string $taxonomy Taxonomy slug.

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.

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

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.

since: 2.3.0
return: void|false Void on success or if the `$object_ids` parameter is empty,
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.

update_term_cache( $terms, $taxonomy = '' )   X-Ref
Updates terms in cache.

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

_get_term_hierarchy( $taxonomy )   X-Ref
Retrieves children of taxonomy as term IDs.

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

_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.

since: 2.3.0
return: array|WP_Error The subset of $terms that are descendants of $term_id.
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

_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.

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

_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.

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

_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.

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

_update_generic_term_count( $terms, $taxonomy )   X-Ref
Updates term count based on number of objects.

Default callback for the 'link_category' taxonomy.

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

_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.

since: 4.2.0
since: 4.3.0 Introduced `$record` parameter. Also, `$term_id` and
return: int|WP_Error When the current term does not need to be split (or cannot be split on the current
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

_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.

since: 4.2.0
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.

_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.

since: 4.2.0
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.

_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.

since: 4.3.0
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.

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.

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

wp_get_split_term( $old_term_id, $taxonomy )   X-Ref
Gets the new term ID corresponding to a previously split term.

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

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.

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

get_term_link( $term, $taxonomy = '' )   X-Ref
Generates a permalink for a taxonomy term archive.

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

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.

since: 2.5.0
param: array $args {

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.

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

get_post_taxonomies( $post = 0 )   X-Ref
Retrieves all taxonomy names for the given post.

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

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.

since: 2.7.0
return: bool|WP_Error WP_Error on input error.
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

is_object_in_taxonomy( $object_type, $taxonomy )   X-Ref
Determines if the given object type is associated with the given taxonomy.

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

get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' )   X-Ref
Gets an array of ancestor IDs for a given object.

since: 3.1.0
since: 4.1.0 Introduced the `$resource_type` argument.
return: int[] An array of IDs of ancestors from lowest to highest in the hierarchy.
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'

wp_get_term_taxonomy_parent_id( $term_id, $taxonomy )   X-Ref
Returns the term's parent's term ID.

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

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.

since: 3.1.0
return: int The new parent for the term.
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.

is_taxonomy_viewable( $taxonomy )   X-Ref
Determines whether a taxonomy is considered "viewable".

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

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.

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



Generated: Tue Mar 19 01:00:02 2024 Cross-referenced by PHPXref 0.7.1