get_terms( array|string $args = array(), array|string $deprecated = '' ): WP_Term[]|int[]|string[]|string|WP_Error
Retrieves the terms in a given taxonomy or list of taxonomies.
Contents
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.
Taxonomy or an array of taxonomies should be passed via the ‘taxonomy’ argument in the $args
array:
$terms = get_terms( array(
'taxonomy' => 'post_tag',
'hide_empty' => false,
) );
Prior to 4.5.0, taxonomy was passed as the first parameter of get_terms()
.
Parameters
-
$args
array|string Optional -
Array or string of arguments. See WP_Term_Query::__construct() for information on accepted arguments.
More Arguments from WP_Term_Query::__construct( ... $query )
Array or query string of term query parameters.
taxonomy
string|string[]Taxonomy name, or array of taxonomy names, to which results should be limited.object_ids
int|int[]Object ID, or array of object IDs. Results will be limited to terms associated with these objects.orderby
stringField(s) to order terms by. Accepts:
- Term fields (
'name'
,'slug'
,'term_group'
,'term_id'
,'id'
,'description'
,'parent'
,'term_order'
). Unless$object_ids
is not empty,'term_order'
is treated the same as'term_id'
. 'count'
to use the number of objects associated with the term.'include'
to match the'order'
of the$include
param.'slug__in'
to match the'order'
of the$slug
param.'meta_value'
'meta_value_num'
.- The value of
$meta_key
. - The array keys of
$meta_query
. 'none'
to omit the ORDER BY clause.
'name'
.- Term fields (
order
stringWhether to order terms in ascending or descending order.
Accepts'ASC'
(ascending) or'DESC'
(descending).
Default'ASC'
.hide_empty
bool|intWhether to hide terms not assigned to any posts. Accepts1|true
or0|false
. Default1|true
.include
int[]|stringArray or comma/space-separated string of term IDs to include.
Default empty array.exclude
int[]|stringArray or comma/space-separated string of term IDs to exclude.
If$include
is non-empty,$exclude
is ignored.
Default empty array.exclude_tree
int[]|stringArray or comma/space-separated string of term IDs to exclude along with all of their descendant terms. If$include
is non-empty,$exclude_tree
is ignored. Default empty array.number
int|stringMaximum number of terms to return. Accepts
(all) or any positive number. Default''
|0
(all). Note that''
|0$number
may not return accurate results when coupled with$object_ids
.
See #41796 for details.offset
intThe number by which to offset the terms query.fields
stringTerm fields to query for. Accepts:
'all'
Returns an array of complete term objects (WP_Term[]
).'all_with_object_id'
Returns an array of term objects with the'object_id'
param (WP_Term[]
). Works only when the$object_ids
parameter is populated.'ids'
Returns an array of term IDs (int[]
).'tt_ids'
Returns an array of term taxonomy IDs (int[]
).'names'
Returns an array of term names (string[]
).'slugs'
Returns an array of term slugs (string[]
).'count'
Returns the number of matching terms (int
).'id=>parent'
Returns an associative array of parent term IDs, keyed by term ID (int[]
).'id=>name'
Returns an associative array of term names, keyed by term ID (string[]
).'id=>slug'
Returns an associative array of term slugs, keyed by term ID (string[]
).
'all'
.count
boolWhether to return a term count. If true, will take precedence over$fields
. Default false.name
string|string[]Name or array of names to return term(s) for.
slug
string|string[]Slug or array of slugs to return term(s) for.
term_taxonomy_id
int|int[]Term taxonomy ID, or array of term taxonomy IDs, to match when querying terms.hierarchical
boolWhether to include terms that have non-empty descendants (even if$hide_empty
is set to true). Default true.search
stringSearch criteria to match terms. Will be SQL-formatted with wildcards before and after.name__like
stringRetrieve terms with criteria by which a term is LIKE$name__like
.description__like
stringRetrieve terms where the description is LIKE$description__like
.pad_counts
boolWhether to pad the quantity of a term's children in the quantity of each term's "count" object variable. Default false.get
stringWhether to return terms regardless of ancestry or whether the terms are empty. Accepts'all'
or''
(disabled). Default''
.child_of
intTerm ID to retrieve child terms of. If multiple taxonomies are passed,$child_of
is ignored. Default 0.parent
intParent term ID to retrieve direct-child terms of.
childless
boolTrue to limit results to terms that have no children.
This parameter has no effect on non-hierarchical taxonomies.
Default false.cache_domain
stringUnique cache key to be produced when this query is stored in an object cache. Default'core'
.update_term_meta_cache
boolWhether to prime meta caches for matched terms. Default true.meta_key
string|string[]Meta key or keys to filter by.meta_value
string|string[]Meta value or values to filter by.meta_compare
stringMySQL operator used for comparing the meta value.
See WP_Meta_Query::__construct() for accepted values and default value.meta_compare_key
stringMySQL operator used for comparing the meta key.
See WP_Meta_Query::__construct() for accepted values and default value.meta_type
stringMySQL data type that the meta_value column will be CAST to for comparisons.
See WP_Meta_Query::__construct() for accepted values and default value.meta_type_key
stringMySQL data type that the meta_key column will be CAST to for comparisons.
See WP_Meta_Query::__construct() for accepted values and default value.meta_query
arrayAn associative array of WP_Meta_Query arguments.
See WP_Meta_Query::__construct() for accepted values.
Default:
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:
''
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
.
View all references
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 );
}
Hooks
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
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.)
As of WordPress 4.6.1, here’s the array that’s returned (to add to Leo’s helpful note above)
If parent => 0 is passed, only top-level terms will be returned
Get categories and subcategories by custom taxonomies:
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 (·):
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:
Get all post categories ordered by count.
String syntax:
Array syntax:
List terms limit to those matching a specific metadata key and metadata value
Meta Query using a custom field, and then ordering using a different custom field.
Get list of terms that match a certain meta_key
If `get_terms` doesnt works for some odd reason with custom taxonomy not showing registered, try using `WP_Term_Query`:
Get all args from here: https://developer.wordpress.org/reference/classes/WP_Term_Query/__construct/
Custom Taxonomy and Sub Category Lists.
Your can use this to create list table also.
Order by parent term ID – not documented, but also works.
Get All Terms id and name in a array for make dropdown select:
list categories( or custom taxonomy ) and subcategory in organazid way
If you have a term assigned to something else than a post, here is a warning:
'hide_empty'
is default true so it only shows terms assigned to posts. So if you get an empty Array returned be aware that terms (e.g. categories) assigned to attachments for example are not shown by default unless you use'hide_empty' => false
:Be very careful as the code below:
can return valid terms, but can also return a
WP_Error
if, for example, the taxonomy is invalid…Therefore this check alone isn’t enough to save you from bugs in your code:
Instead, better to use the one below:
Categories and Tags are the two pre-defined Taxonomies. The Taxonomy Name, when included as an element ‘taxonomy’ of the array specified as the first parameter $args, has a value of ‘category’ for Categories and ‘post_tag’ for Tags.
'taxonomy' => 'category'
'taxonomy' => 'post_tag'
Loop through taxonomy and list all subcategories.
Get all child taxonomy of a parent taxonomy
Get Terms filtered by first letter
Get terms ordered by value of meta-key: