How to use the New WP_Term_Query in WordPress 4.6

The latest version of WordPress 4.6 brings a new way of querying taxonomies. Sometimes depending on the requirements, you need a way to get a specific list of taxonomies on your website. These can be built in taxonomies like “category”, or custom made taxonomies that you’ve created on your own. WordPress already has a function to query these taxnomies called “get_terms”.

“get_terms” Usage Before Version 4.5

The usage structure of “get_terms” changed before being supplanted by WP_Term_Query. Before version 4.5, here was a sample usage of “get_terms”:

function terms_test() {
	$taxonomy = 'category';
	$term_args=array(
		'hide_empty' => false,
		'orderby' => 'name',
		'order' => 'ASC'
	);
	$tax_terms = get_terms($taxonomy, $term_args);
	foreach ( $tax_terms as $tax_term ) {
	    	echo $tax_term->name;
	}

}
add_action( 'init', 'terms_test' );

Note that there are two arguments for get_terms”. The first is the name (or array) of a taxonomy, and the second argument takes a number of arguments specifying a multitude of parameters by which the taxonomy is to be filtered. In the above example, I’m using the built-in “category” taxonomy, ordered by name in ascending order, and also an instruction to show empty categories as well.

This will return an output like this on my test blog:

You can see that each term name has been returned in alphabetical order as expected. In case you’re wondering, I’m sending the messages to the browser console as shown in this earlier tutorial here.

“get_terms” Usage After Version 4.5

In version 4.5, “get_terms” modified its parameters to include just one instead of two. Specifically, it now allowed the first “taxonomy” term to be bundled into the argument variable itself. It could still be a string, or an array so no flexibility was lost. Here’s the modified code for “get_terms” after 4.5:

function terms_test() {
	$term_args = array(
		'taxonomy' => 'category',
		'hide_empty' => false,
		'orderby' => 'name',
		'order' => 'ASC'
	);
	$tax_terms = get_terms($term_args);
	foreach ( $tax_terms as $tax_term ) {
	    	echo $tax_term->name;
	}

}
add_action( 'init', 'terms_test' );

Notice the new “taxonomy” parameter that has been rolled into the main set of arguments. And we’ve lost the need to define an additional parameter for the same. As a result, “get_terms” now just has one argument instead of two. The two functions shown here are equivalent. The first is deprecated, so using it is not advisable.

Using WP_Term_Query in Version 4.6 and Above

In version 4.6 of WordPress, the developers decided that “get_terms” was an anomaly and didn’t behave consistently with how other object in the WordPress database are queries. For example, WP_Query, WP_User_Query and WP_Comment_Query share a similar structure and they’re implemented in a way that makes them easy and intuitive to use. This behavior was simply extended to taxonomy terms with the introduction of WP_Term_Query.

The behavior is similar to how “get_terms” works. For example, here is the equivalent code using WP_Term_Query for the above two functions instead of “get_terms:

function terms_test() {

	$args = array (
	'taxonomy'               => array( 'category' ),
	'order'                  => 'ASC',
	'orderby'                => 'name',
	'hide_empty'             => false,
	);

	$term_query = new WP_Term_Query( $args );

	if ( ! empty( $term_query ) && ! is_wp_error( $term_query ) ) {
		foreach ( $term_query ->terms as $term )
	        echo $term->name;

	}

	else
		echo "Nothing found";
}
add_action( 'init', 'terms_test' );

The new WP_Term_Query constructor is highlighted in bold. Like “get_terms”, it accepts an array of arguments and then creates a list of objects that match the criteria. It might not make too much of a difference in terms of syntax, but there’s a lot going on behind the scenes that makes this a more efficient way to query a taxonomy structure. One of the biggest differences is caching. Uncached queries trigger an SQL statement each and every time they are run. “get_terms” has no consistent caching behavior and is therefore one of the slowest functions around.

With the implementation of WP_Term_Query, this problem is now solved. If you want help getting used to how it works, you can use this constructor page to filter down the variables and get the exact taxonomy list you’re looking for