Summery Summery
Retrieve the terms in a given taxonomy or list of taxonomies.
Syntax Syntax
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
-
(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 Return
(WP_Term[]|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
* * The {@see 'list_terms_exclusions'} filter passes the compiled exclusions along with * the $args. * * The {@see '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, * ) ); * * @since 2.3.0 * @since 4.2.0 Introduced 'name' and 'childless' parameters. * @since 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. * @since 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. * @since 4.8.0 Introduced 'suppress_filter' parameter. * * @internal The `$deprecated` parameter is parsed for backward compatibility only. * * @param array|string $args Optional. Array or string of arguments. See WP_Term_Query::__construct() * for information on accepted arguments. Default empty. * @param array|string $deprecated 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. * @return WP_Term[]|int|WP_Error Array of WP_Term instances, a count thereof, * or WP_Error if any of the taxonomies do not exist. */ 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'];
Advertisement
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. |