get_terms() WordPress Function
The get_terms() function retrieves the terms in a given taxonomy. It is similar to the get_categories() function, but with one key difference: you can specify the taxonomy for which you want to retrieve the terms. The get_terms() function accepts two parameters: the taxonomy and an array of arguments. The taxonomy parameter is required, and it tells the function which taxonomy to use. The array of arguments is optional, but it allows you to specify how the terms should be ordered, what fields should be returned, and how many terms to return. Here is a simple example of how the get_terms() function can be used: $terms = get_terms( 'category', array( 'orderby' => 'name', 'order' => 'ASC', 'fields' => 'all', 'number' => 10, ) ); This example will retrieve the first 10 terms in the category taxonomy, ordered alphabetically by name. The get_terms() function is a useful tool for retrieving terms in a specific taxonomy. With a little bit of configuration, you can customize the function to meet your specific needs.
get_terms( array|string $args = array(), array|string $deprecated = '' ) #
Retrieves 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 return type varies depending on the value passed to $args['fields']. See WP_Term_Query::get_terms() for details. In all cases, a WP_Error object will be returned if an invalid taxonomy is requested.
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
- $args
(array|string)(Optional) Array or string of arguments. See WP_Term_Query::__construct() for information on accepted arguments.
Default value: array()
- $deprecated
(array|string)(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
(WP_Term[]|int[]|string[]|string|WP_Error) Array of terms, a count thereof as a numeric string, or WP_Error if any of the taxonomies do not exist. See the function description for more information.
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|null $taxonomies An array of taxonomies if known.
* @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 codeCollapse full source codeView on TracView on GitHub
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. |