get_term()
概述
get_term() 函数用于通过 term ID 从数据库中获取完整的 term 数据，并返回一个 WP_Term 对象或数组。它支持多种输入类型和输出格式，并应用过滤器以允许开发者修改 term 对象。
关键要点
- 函数核心功能：根据 term ID 获取 term 数据，支持整数、stdClass 对象或 WP_Term 对象作为输入。
- 参数说明：$term 为必需参数，可以是整数、stdClass 对象或 WP_Term 对象；$taxonomy 为可选参数，指定 term 所属的分类法；$output 控制返回类型（OBJECT、ARRAY_A 或 ARRAY_N）；$filter 定义字段的 sanitize 方式。
- 返回值：成功时返回 WP_Term 对象或数组，失败时返回 WP_Error 或 null。
- 过滤器应用：函数使用两个钩子：'get_term' 通用过滤器和动态的 'get_$taxonomy' 过滤器，允许在返回前修改 term 对象。
- 缓存机制：利用 WP Object Cache 缓存 term 数据，减少数据库查询。
代码示例
$term = get_term( $term_id, $taxonomy );
$slug = $term->slug;
$name = $term->name;
$desc = $term->description;注意事项
- 确保 $term 属于指定的 $taxonomy，否则可能返回错误。
- 过滤器必须返回 term 对象，否则可能影响后续处理。
- 从 4.4.0 版本起，默认返回 WP_Term 对象，$taxonomy 参数变为可选。
Gets 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
$termint|WP_Term|objectrequired-
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 aWP_Termobject with the$termdata.
IfWP_Term, will return$term. $taxonomystringoptional-
Taxonomy name that
$termis part of. $outputstringoptional-
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 $filterstringoptional-
How to sanitize term fields. Default
'raw'.
Source
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;
$old_term = $_term;
/**
* Filters a taxonomy term object.
*
* The 'get_$taxonomy' hook is also available for targeting a specific
* 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_term', $_term, $taxonomy );
/**
* Filters a taxonomy term object.
*
* The dynamic portion of the hook name, `$taxonomy`, refers
* to the slug of the term's taxonomy.
*
* Possible hook names include:
*
* - `get_category`
* - `get_post_tag`
*
* @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.
if ( $_term !== $old_term || $_term->filter !== $filter ) {
$_term->filter( $filter );
}
if ( ARRAY_A === $output ) {
return $_term->to_array();
} elseif ( ARRAY_N === $output ) {
return array_values( $_term->to_array() );
}
return $_term;
}
Hooks
- apply_filters( ‘get_term’, WP_Term $_term, string $taxonomy )
-
Filters a taxonomy term object.
- apply_filters( “get_{$taxonomy}”, WP_Term $_term, string $taxonomy )
-
Filters a taxonomy term object.
Skip to note 3 content
Codex
Examples
Get Term offers some handy information, but unfortunately lacks a link value.
Gives you term slug: e.g.: term-slug-example
Gives you term name: e.g. Term Name Example
Gives you term description: e.g. This is my new cool custom term.
Skip to note 4 content
Lance Cleveland
get_term()utilizes the WP Object Cache to store previously-fetched term data. This helps avoid subsequent data I/O calls from the database to read term data. For example:$term = get_term( 1 , 'store' ); echo $term->name; $term = get_term( 1 , ' store' ); echo $term->slug;This overly-simple example will only perform a single select query on the database. The second get_term will use the WP Object Cache to fetch the previous term object from memory.