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. 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
$argsarray|stringoptional
Array or string of arguments. See WP_Term_Query::__construct() for information on accepted arguments. Default empty array.Default: array()
$deprecatedarray|stringoptional
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 empty.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.
Hooks fired · 1
One hook fires while get_terms() runs, in this order:
1316functionget_terms($args=array(),$deprecated=''){1317$term_query=newWP_Term_Query();13181319$defaults=array(1320'suppress_filter'=>false,1321);13221323/*1324 * Legacy argument format ($taxonomy, $args) takes precedence.1325 *1326 * We detect legacy argument format by checking if1327 * (a) a second non-empty parameter is passed, or1328 * (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies)1329 */1330$_args=wp_parse_args($args);1331$key_intersect=array_intersect_key($term_query->query_var_defaults,(array)$_args);1332$do_legacy_args=$deprecated||empty($key_intersect);13331334if($do_legacy_args){1335$taxonomies=(array)$args;1336$args=wp_parse_args($deprecated,$defaults);1337$args['taxonomy']=$taxonomies;1338}else{1339$args=wp_parse_args($args,$defaults);1340if(isset($args['taxonomy'])&&null!==$args['taxonomy']){1341$args['taxonomy']=(array)$args['taxonomy'];1342}1343}13441345if(!empty($args['taxonomy'])){1346foreach($args['taxonomy']as$taxonomy){1347if(!taxonomy_exists($taxonomy)){1348returnnewWP_Error('invalid_taxonomy',__('Invalid taxonomy.'));1349}1350}1351}13521353// Don't pass suppress_filter to WP_Term_Query.1354$suppress_filter=$args['suppress_filter'];1355unset($args['suppress_filter']);13561357$terms=$term_query->query($args);13581359// Count queries are not filtered, for legacy reasons.1360if(!is_array($terms)){1361return$terms;1362}13631364if($suppress_filter){1365return$terms;1366}13671368/**1369 * Filters the found terms.1370 *1371 * @since 2.3.01372 * @since 4.6.0 Added the `$term_query` parameter.1373 *1374 * @param array $terms Array of found terms.1375 * @param array|null $taxonomies An array of taxonomies if known.1376 * @param array $args An array of get_terms() arguments.1377 * @param WP_Term_Query $term_query The WP_Term_Query object.1378 */1379returnapply_filters('get_terms',$terms,$term_query->query_vars['taxonomy'],$term_query->query_vars,$term_query);1380}
History
Introduced in 4.8.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
4.8.0
Introduced 'suppress_filter' parameter.from the docblock
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.from the docblock
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.from the docblock
4.2.0
Introduced 'name' and 'childless' parameters.from the docblock
2.3.0
Introduced.from the docblock
About this page
Parsed data
Generated from the wordpress-develop 6.7.7 tag, from src/wp-includes/taxonomy.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.