get_terms( string|array $args = array(), array $deprecated = '' )
Retrieve the terms in a given taxonomy or list of taxonomies.
Description Description
You can fully inject any customizations to the query before it is sent, as well as control the output with a filter.
The ‘get_terms’ filter will be called when the cache has the term and will pass the found term along with the array of $taxonomies and array of $args. This filter is also called before the array of terms is passed and will pass the array of terms, along with the $taxonomies and $args.
The ‘list_terms_exclusions’ filter passes the compiled exclusions along with the $args.
The ‘get_terms_orderby’ filter passes the ORDER BY
clause for the query along with the $args array.
Prior to 4.5.0, the first parameter of get_terms()
was a taxonomy or list of taxonomies:
$terms = get_terms( 'post_tag', array(
'hide_empty' => false,
) );
Since 4.5.0, taxonomies should be passed via the ‘taxonomy’ argument in the $args
array:
$terms = get_terms( array(
'taxonomy' => 'post_tag',
'hide_empty' => false,
) );
Parameters Parameters
- $args
-
(string|array) (Optional) Array or string of arguments. See WP_Term_Query::__construct() for information on accepted arguments.
Default value: array()
- $deprecated
-
(array) (Optional) Argument array, when using the legacy function parameter format. If present, this parameter will be interpreted as
$args
, and the first function parameter will be parsed as a taxonomy or array of taxonomies.Default value: ''
Return Return
(array|int|WP_Error) List of WP_Term instances and their children. Will return WP_Error, if any of $taxonomies do not exist.
Source Source
File: wp-includes/taxonomy.php
function get_terms( $args = array(), $deprecated = '' ) { $term_query = new WP_Term_Query(); $defaults = array( 'suppress_filter' => false, ); /* * Legacy argument format ($taxonomy, $args) takes precedence. * * We detect legacy argument format by checking if * (a) a second non-empty parameter is passed, or * (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies) */ $_args = wp_parse_args( $args ); $key_intersect = array_intersect_key( $term_query->query_var_defaults, (array) $_args ); $do_legacy_args = $deprecated || empty( $key_intersect ); if ( $do_legacy_args ) { $taxonomies = (array) $args; $args = wp_parse_args( $deprecated, $defaults ); $args['taxonomy'] = $taxonomies; } else { $args = wp_parse_args( $args, $defaults ); if ( isset( $args['taxonomy'] ) && null !== $args['taxonomy'] ) { $args['taxonomy'] = (array) $args['taxonomy']; } } if ( ! empty( $args['taxonomy'] ) ) { foreach ( $args['taxonomy'] as $taxonomy ) { if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } } } // Don't pass suppress_filter to WP_Term_Query. $suppress_filter = $args['suppress_filter']; unset( $args['suppress_filter'] ); $terms = $term_query->query( $args ); // Count queries are not filtered, for legacy reasons. if ( ! is_array( $terms ) ) { return $terms; } if ( $suppress_filter ) { return $terms; } /** * Filters the found terms. * * @since 2.3.0 * @since 4.6.0 Added the `$term_query` parameter. * * @param array $terms Array of found terms. * @param array $taxonomies An array of taxonomies. * @param array $args An array of get_terms() arguments. * @param WP_Term_Query $term_query The WP_Term_Query object. */ return apply_filters( 'get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query ); }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
4.8.0 | Introduced 'suppress_filter' parameter. |
4.5.0 | Changed the function signature so that the $args array can be provided as the first parameter. Introduced 'meta_key' and 'meta_value' parameters. Introduced the ability to order results by metadata. |
4.4.0 | Introduced the ability to pass 'term_id' as an alias of 'id' for the orderby parameter. Introduced the 'meta_query' and 'update_term_meta_cache' parameters. Converted to return a list of WP_Term objects. |
4.2.0 | Introduced 'name' and 'childless' parameters. |
2.3.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
All get_terms attributes with default values:
(I try default from this article and it didn’t work. This works.)
Expand full source codeCollapse full source code
As of WordPress 4.6.1, here’s the array that’s returned (to add to Leo’s helpful note above)
Expand full source codeCollapse full source code
If parent => 0 is passed, only top-level terms will be returned
Get all post categories ordered by count.
String syntax:
Array syntax:
Get all post categories ordered by count.
String syntax:
Array syntax:
Get all the links categories:
List all the terms in a custom taxonomy, without a link:
List all the terms, with link to term archive, separated by an interpunct (ยท):
Expand full source codeCollapse full source code
Get categories and subcategories by custom taxonomies:
Expand full source codeCollapse full source code
Working with Advanced Custom Fields (field type: Taxonomy, output: Object) for filtering taxonomies.
Case: Create a filter with main categories defined by ACF field, and all another should belongs to *others*.
Solution:
Expand full source codeCollapse full source code
List terms limit to those matching a specific metadata key and metadata value
Order by parent term ID – not documented, but also works.
Meta Query using a custom field, and then ordering using a different custom field.
Expand full source codeCollapse full source code
Get Terms filtered by first letter
Get terms ordered by value of meta-key:
Get Categories by custom post type with dropdown:
Expand full source codeCollapse full source code