get_terms( string|array $args = array(), array $deprecated = '' )
Retrieve the terms in a given taxonomy or list of taxonomies.
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 WP-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 WP-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
- $args
-
(Optional) Array or string of arguments. See WP_Term_Query::__construct() for information on accepted arguments.
Default value: array()
- $deprecated
-
(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
(array|int|WP_Error) List of WP_Term instances and their children. Will return WP_Error, if any of $taxonomies do not exist.
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 WP-2.3.0
* @since WP-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 );
}
Changelog
| Version | Description |
|---|---|
| WP-4.8.0 | Introduced 'suppress_filter' parameter. |
| WP-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. |
| WP-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. |
| WP-4.2.0 | Introduced 'name' and 'childless' parameters. |
| WP-2.3.0 | Introduced. |