WordPress at a glance

get_the_terms() WP 2.5.0

Gets the taxonomy elements (terms) that are attached to the specified post.

This function can be used inside The Loop. Or you can pass it the ID of the post the terms of whose you want to get.

This function is completely identical to wp_get_object_terms( $id, $taxonomy ). The difference is that this function works with the cache and there is a filter get_the_terms.

Works based on: wp_get_object_terms()
✈ 1 time = 0.005139s = very slow | 50000 times = 1.66s = fast | PHP 7.1.2, WP 4.8
Hooks in function
Return

Array/false/WP_Error.

  • An array of WP_Term objects on success.
  • false if there are no terms or the specified post does not exist.
  • WP_Error in other cases.
Array
(
	[0] => stdClass Object (
			[term_id]          => 21
			[name]             => Term Name
			[slug]             => term-name
			[term_group]       => 0
			[term_taxonomy_id] => 21
			[taxonomy]         => post_tag
			[description]      => 
			[parent]           => 0
			[count]            => 8
			[filter]           => raw
		)

	[1] => stdClass Object (
		...
		)
	...
)

Usage

get_the_terms( $post, $taxonomy );
$post(int/WP_Post) (required)
Post ID or object.
$taxonomy(string) (required)
Taxonomy name.

Examples

#1. Display links of the 'my_tax' taxonomy elements attached to the post 10

$cur_terms = get_the_terms( 10, 'my_tax' );
if( is_array( $cur_terms ) ){
	foreach( $cur_terms as $cur_term ){
		echo '<a href="'. get_term_link( $cur_term->term_id, $cur_term->taxonomy ) .'">'. $cur_term->name .'</a>,';
	}
}

The same can be done inside The Loop:

Display the attached terms for each post. To do this, specify the post ID dynamically ($post->ID):

$cur_terms = get_the_terms( $post->ID, 'my_tax' );
if( is_array( $cur_terms ) ){
	foreach( $cur_terms as $cur_term ){
		echo '<a href="'. get_term_link( $cur_term->term_id, $cur_term->taxonomy ) .'">'. $cur_term->name .'</a>,';
	}
}

#2. Get only the first term

Let's say we get the post terms and we need to get the data of only one term (taxonomy element). But this function returns an array of term objects. The example below shows how to get the first term from the array.

$terms = get_the_terms( $post->ID, 'my_tax' );
if( $terms ){
	$term = array_shift( $terms ); // get first

	// now you can display the name of the term
	echo $term->name;
}

#3. Get the top-level term for the specified or current post in The Loop

Here we have a custom function based on get_the_terms():

/**
 * Gets the top-level term for the specified or current post in The Loop.
 * 
 * @param  string          $taxonomy      
 * @param  int/object      $post_id   ID or object of the post
 *
 * @return string/wp_error Объект термина или false
 */
function get_top_term( $taxonomy, $post_id = 0 ){
	if( isset($post_id->ID) ) $post_id = $post_id->ID;
	if( ! $post_id )          $post_id = get_the_ID();

	$terms = get_the_terms( $post_id, $taxonomy );

	if( ! $terms || is_wp_error($terms) )
		return $terms;

	// only first
	$term = array_shift( $terms );

	// find TOP
	$parent_id = $term->parent;
	while( $parent_id ){
		$term = get_term_by( 'id', $parent_id, $term->taxonomy );
		$parent_id = $term->parent;
	}

	return $term;
}

Usage:

$top_term = get_top_term( 'category' );
echo $top_term->name;

Code of get the terms: wp-includes/category-template.php WP 5.2.2

<?php
function get_the_terms( $post, $taxonomy ) {
	if ( ! $post = get_post( $post ) ) {
		return false;
	}

	$terms = get_object_term_cache( $post->ID, $taxonomy );
	if ( false === $terms ) {
		$terms = wp_get_object_terms( $post->ID, $taxonomy );
		if ( ! is_wp_error( $terms ) ) {
			$term_ids = wp_list_pluck( $terms, 'term_id' );
			wp_cache_add( $post->ID, $term_ids, $taxonomy . '_relationships' );
		}
	}

	/**
	 * Filters the list of terms attached to the given post.
	 *
	 * @since 3.1.0
	 *
	 * @param WP_Term[]|WP_Error $terms    Array of attached terms, or WP_Error on failure.
	 * @param int                $post_id  Post ID.
	 * @param string             $taxonomy Name of the taxonomy.
	 */
	$terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy );

	if ( empty( $terms ) ) {
		return false;
	}

	return $terms;
}

Related Functions

From tag: Term (taxonomies terms)

More from category: For posts

No comments
    Hello, !     Log In . Register