get_term( int|WP_Term|object $term, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' )
Get all Term data from database by Term ID.
Description
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.
‘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.
‘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.
See also
sanitize_term_field(): The $context param lists the available values for get_term_by() $filter param.
Parameters
- $term
-
(Required) 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_Termobject corresponding to the$termdata. IfWP_Term, will return$term. - $taxonomy
-
(Optional) Taxonomy name that $term is part of.
Default value: ''
- $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 value: OBJECT
- $filter
-
(Optional) default is raw or no ClassicPress defined filter will applied.
Default value: 'raw'
Return
(array|WP_Term|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.
Source
File: wp-includes/taxonomy.php
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;
}
/**
* Filters a term.
*
* @since WP-2.3.0
* @since WP-4.4.0 `$_term` can now also be a WP_Term object.
*
* @param int|WP_Term $_term Term object or ID.
* @param string $taxonomy The taxonomy slug.
*/
$_term = apply_filters( 'get_term', $_term, $taxonomy );
/**
* Filters a taxonomy.
*
* The dynamic portion of the filter name, `$taxonomy`, refers
* to the taxonomy slug.
*
* @since WP-2.3.0
* @since WP-4.4.0 `$_term` can now also be a WP_Term object.
*
* @param int|WP_Term $_term Term object or ID.
* @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 ( $output == ARRAY_A ) {
return $_term->to_array();
} elseif ( $output == ARRAY_N ) {
return array_values( $_term->to_array() );
}
return $_term;
}
Changelog
| Version | Description |
|---|---|
| WP-4.4.0 | Converted to return a WP_Term object if $output is OBJECT. The $taxonomy parameter was made optional. |
| WP-2.3.0 | Introduced. |