WordPress Version: 5.4
/**
* Get 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.
*
* @todo Better formatting for DocBlock
*
* @since 2.3.0
* @since 4.4.0 Converted to return a WP_Term object if `$output` is `OBJECT`.
* The `$taxonomy` parameter was made optional.
*
* @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
*
* @param int|WP_Term|object $term If integer, term data will be fetched from the database, or from the cache if
* available. If stdClass object (as in the results of a database query), will apply
* filters and return a `WP_Term` object corresponding to the `$term` data. If `WP_Term`,
* will return `$term`.
* @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 correspond to
* a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $filter Optional, default is raw or no WordPress defined filter will applied.
* @return WP_Term|array|WP_Error|null Object of the type specified by `$output` on success. When `$output` is 'OBJECT',
* a WP_Term instance is returned. If taxonomy does not exist, a WP_Error is
* returned. Returns null for miscellaneous failure.
*/
function get_term($term, $taxonomy = '', $output = OBJECT, $filter = 'raw')
{
if (empty($term)) {
return new WP_Error('invalid_term', __('Empty Term.'));
}
if ($taxonomy && !taxonomy_exists($taxonomy)) {
return new WP_Error('invalid_taxonomy', __('Invalid taxonomy.'));
}
if ($term instanceof WP_Term) {
$_term = $term;
} elseif (is_object($term)) {
if (empty($term->filter) || 'raw' === $term->filter) {
$_term = sanitize_term($term, $taxonomy, 'raw');
$_term = new WP_Term($_term);
} else {
$_term = WP_Term::get_instance($term->term_id);
}
} else {
$_term = WP_Term::get_instance($term, $taxonomy);
}
if (is_wp_error($_term)) {
return $_term;
} elseif (!$_term) {
return null;
}
// Ensure for filters that this is not empty.
$taxonomy = $_term->taxonomy;
/**
* Filters a taxonomy term object.
*
* @since 2.3.0
* @since 4.4.0 `$_term` is now a `WP_Term` object.
*
* @param WP_Term $_term Term object.
* @param string $taxonomy The taxonomy slug.
*/
$_term = apply_filters('get_term', $_term, $taxonomy);
/**
* Filters a taxonomy term object.
*
* The dynamic portion of the filter name, `$taxonomy`, refers
* to the slug of the term's taxonomy.
*
* @since 2.3.0
* @since 4.4.0 `$_term` is now a `WP_Term` object.
*
* @param WP_Term $_term Term object.
* @param string $taxonomy The taxonomy slug.
*/
$_term = apply_filters("get_{$taxonomy}", $_term, $taxonomy);
// Bail if a filter callback has changed the type of the `$_term` object.
if (!$_term instanceof WP_Term) {
return $_term;
}
// Sanitize term, according to the specified filter.
$_term->filter($filter);
if (ARRAY_A === $output) {
return $_term->to_array();
} elseif (ARRAY_N === $output) {
return array_values($_term->to_array());
}
return $_term;
}