get_terms

Retrieve the terms in a given taxonomy or list of taxonomies.

Description

(array|int|WP_Error) get_terms( (array) $args = array(), (string) $deprecated = '' ); 

You can fully inject any customizations to the query before it is sent, as well as control the output with a filter.

The 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 filter passes the compiled exclusions along with the $args.

The 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:

hide_empty => false,

Since 4.5.0, taxonomies should be passed via the taxonomy argument in the $args array:

taxonomy => post_tag, hide_empty => false,

Returns (array|int|WP_Error)

List of WP_Term instances and their children. Will return WP_Error, if any of $taxonomies do not exist.

Parameters (2)

0. $args — Optional. (array) => array()
Array or string of arguments to get terms.

Options

  • taxonomy (string|array) => ''

    Taxonomy name, or array of taxonomies, to which results should be limited.

  • orderby (string) => 'name'

    Field(s) to order terms by. Accepts term fields ('name', slug,, term_group, term_id , id, description), count for term taxonomy count, include to match the order of the $include param, meta_value, meta_value_num, the value of $meta_key, the array keys of $meta_query, or none to omit the ORDER BY clause.

  • order (string) => 'ASC'

    Whether to order terms in ascending or descending order. Accepts ASC (ascending) or DESC (descending).

  • hide_empty (bool|int) => 1

    Whether to hide terms not assigned to any posts. Accepts 1|true or 0|false.

  • include (array|string) => array()

    Array or comma/space-separated string of term ids to include.

  • exclude (array|string) => array()

    Array or comma/space-separated string of term ids to exclude. If $include is non-empty, $exclude is ignored.

  • exclude_tree (array|string) => array()

    Array 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.

  • number (int|string) => ''

    Maximum number of terms to return. Accepts ''|0 (all) or any positive number.

  • offset (int) => 0

    The number by which to offset the terms query.

  • fields (string) => 'all'

    Term fields to query for. Accepts all (returns an array of complete term objects), ids (returns an array of ids), id=>parent (returns an associative array with ids as keys, parent term IDs as values), names (returns an array of term names), count (returns the number of matching terms), id=>name (returns an associative array with ids as keys, term names as values), or id=>slug (returns an associative array with ids as keys, term slugs as values).

  • name (string|array) => ''

    Name or array of names to return term(s) for.

  • slug (string|array) => ''

    Slug or array of slugs to return term(s) for.

  • hierarchical (bool) => true

    Whether to include terms that have non-empty descendants (even if $hide_empty is set to true).

  • search (string) => ''

    Search criteria to match terms. Will be SQL-formatted with wildcards before and after.

  • name__like (string) => ''

    Retrieve terms with criteria by which a term is LIKE $name__like.

  • description__like (string) => ''

    Retrieve terms where the description is LIKE $description__like.

  • pad_counts (bool) => false

    Whether to pad the quantity of a term's children in the quantity of each term's count object variable.

  • get (string) => ''

    Whether to return terms regardless of ancestry or whether the terms are empty. Accepts all or empty (disabled).

  • child_of (int) => 0

    Term ID to retrieve child terms of. If multiple taxonomies are passed, $child_of is ignored.

  • parent (int|string) => ''

    Parent term ID to retrieve direct-child terms of.

  • childless (bool) => false

    True to limit results to terms that have no children. This parameter has no effect on non-hierarchical taxonomies.

  • cache_domain (string) => 'core'

    Unique cache key to be produced when this query is stored in an object cache.

  • update_term_meta_cache (bool) => true

    Whether to prime meta caches for matched terms.

  • meta_query (array) => null

    Meta query clauses to limit retrieved terms by. See WP_Meta_Query..

  • meta_key (string) => ''

    Limit terms to those matching a specific metadata key. Can be used in conjunction with $meta_value..

array(

    /**
     * Taxonomy name, or array of taxonomies, to which results should be limited.
     *
     * @type string|array
     * @default ''
     */
    'taxonomy' => '',

    /**
     * Field(s) to order terms by. Accepts term fields ('name', 'slug', 'term_group', 'term_id',
     * 'id', 'description'), 'count' for term taxonomy count, 'include' to match the 'order' of the
     * $include param, 'meta_value', 'meta_value_num', the value of `$meta_key`, the array keys
     * of `$meta_query`, or 'none' to omit the ORDER BY clause.
     *
     * @type string
     * @default 'name'
     */
    'orderby' => 'name',

    /**
     * Whether to order terms in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC'
     * (descending).
     *
     * @type string
     * @default 'ASC'
     */
    'order' => 'ASC',

    /**
     * Whether to hide terms not assigned to any posts. Accepts 1|true or 0|false.
     *
     * @type bool|int
     * @default 1
     */
    'hide_empty' => 1,

    /**
     * Array or comma/space-separated string of term ids to include.
     *
     * @type array|string
     * @default array()
     */
    'include' => array(),

    /**
     * Array or comma/space-separated string of term ids to exclude. If $include is non-empty,
     * $exclude is ignored.
     *
     * @type array|string
     * @default array()
     */
    'exclude' => array(),

    /**
     * Array 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.
     *
     * @type array|string
     * @default array()
     */
    'exclude_tree' => array(),

    /**
     * Maximum number of terms to return. Accepts ''|0 (all) or any positive number.
     *
     * @type int|string
     * @default ''
     */
    'number' => '',

    /**
     * The number by which to offset the terms query.
     *
     * @type int
     */
    'offset' => 0,

    /**
     * Term fields to query for. Accepts 'all' (returns an array of complete term objects), 'ids'
     * (returns an array of ids), 'id=>parent' (returns an associative array with ids as keys,
     * parent term IDs as values), 'names' (returns an array of term names), 'count' (returns the
     * number of matching terms), 'id=>name' (returns an associative array with ids as keys, term
     * names as values), or 'id=>slug' (returns an associative array with ids as keys, term slugs as
     * values).
     *
     * @type string
     * @default 'all'
     */
    'fields' => 'all',

    /**
     * Optional. Name or array of names to return term(s) for.
     *
     * @type string|array
     * @default ''
     * @optional
     */
    'name' => '',

    /**
     * Optional. Slug or array of slugs to return term(s) for.
     *
     * @type string|array
     * @default ''
     * @optional
     */
    'slug' => '',

    /**
     * Whether to include terms that have non-empty descendants (even if $hide_empty is set to
     * true).
     *
     * @type bool
     * @default true
     */
    'hierarchical' => true,

    /**
     * Search criteria to match terms. Will be SQL-formatted with wildcards before and after.
     *
     * @type string
     * @default ''
     */
    'search' => '',

    /**
     * Retrieve terms with criteria by which a term is LIKE $name__like.
     *
     * @type string
     * @default ''
     */
    'name__like' => '',

    /**
     * Retrieve terms where the description is LIKE $description__like.
     *
     * @type string
     * @default ''
     */
    'description__like' => '',

    /**
     * Whether to pad the quantity of a term's children in the quantity of each term's "count" object
     * variable.
     *
     * @type bool
     * @default false
     */
    'pad_counts' => false,

    /**
     * Whether to return terms regardless of ancestry or whether the terms are empty. Accepts 'all'
     * or empty (disabled).
     *
     * @type string
     * @default ''
     */
    'get' => '',

    /**
     * Term ID to retrieve child terms of. If multiple taxonomies are passed, $child_of is ignored.
     *
     * @type int
     */
    'child_of' => 0,

    /**
     * Parent term ID to retrieve direct-child terms of.
     *
     * @type int|string
     * @default ''
     */
    'parent' => '',

    /**
     * True to limit results to terms that have no children. This parameter has no effect on
     * non-hierarchical taxonomies.
     *
     * @type bool
     * @default false
     */
    'childless' => false,

    /**
     * Unique cache key to be produced when this query is stored in an object cache.
     *
     * @type string
     * @default 'core'
     */
    'cache_domain' => 'core',

    /**
     * Whether to prime meta caches for matched terms.
     *
     * @type bool
     * @default true
     */
    'update_term_meta_cache' => true,

    /**
     * Meta query clauses to limit retrieved terms by. See `WP_Meta_Query`.
     *
     * @type array
     * @default null
     */
    'meta_query' => null,

    /**
     * Limit terms to those matching a specific metadata key. Can be used in conjunction with
     * `$meta_value`.
     *
     * @type string
     * @default ''
     */
    'meta_key' => ''
);        

1. $deprecated — Optional. (string) => ''
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.

Usage

  1. if ( !function_exists( 'get_terms' ) ) { 
  2. require_once ABSPATH . WPINC . '/taxonomy.php'; 
  3.  
  4. // Optional. Array or string of arguments to get terms. 
  5. $args = array( 
  6. 'taxonomy' => '', 
  7. 'orderby' => 'name', 
  8. 'order' => 'ASC', 
  9. 'hide_empty' => 1, 
  10. 'include' => array(), 
  11. 'exclude' => array(), 
  12. 'exclude_tree' => array(), 
  13. 'number' => '', 
  14. 'offset' => 0, 
  15. 'fields' => 'all', 
  16. 'name' => '', 
  17. 'slug' => '', 
  18. 'hierarchical' => true, 
  19. 'search' => '', 
  20. 'name__like' => '', 
  21. 'description__like' => '', 
  22. 'pad_counts' => false, 
  23. 'get' => '', 
  24. 'child_of' => 0, 
  25. 'parent' => '', 
  26. 'childless' => false, 
  27. 'cache_domain' => 'core', 
  28. 'update_term_meta_cache' => true, 
  29. 'meta_query' => null, 
  30. 'meta_key' => '' 
  31. ); 
  32. $deprecated = ''; 
  33.  
  34. // NOTICE! Understand what this does before running. 
  35. $result = get_terms($args, $deprecated); 
  36.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/taxonomy.php  
  1. function get_terms( $args = array(), $deprecated = '' ) { 
  2. global $wpdb; 
  3.  
  4. $term_query = new WP_Term_Query(); 
  5.  
  6. /** 
  7. * Legacy argument format ($taxonomy, $args) takes precedence. 
  8. * We detect legacy argument format by checking if 
  9. * (a) a second non-empty parameter is passed, or 
  10. * (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies) 
  11. */ 
  12. $_args = wp_parse_args( $args ); 
  13. $key_intersect = array_intersect_key( $term_query->query_var_defaults, (array) $_args ); 
  14. $do_legacy_args = $deprecated || empty( $key_intersect ); 
  15.  
  16. if ( $do_legacy_args ) { 
  17. $taxonomies = (array) $args; 
  18. $args = wp_parse_args( $deprecated ); 
  19. $args['taxonomy'] = $taxonomies; 
  20. } else { 
  21. $args = wp_parse_args( $args ); 
  22. if ( isset( $args['taxonomy'] ) && null !== $args['taxonomy'] ) { 
  23. $args['taxonomy'] = (array) $args['taxonomy']; 
  24.  
  25. if ( ! empty( $args['taxonomy'] ) ) { 
  26. foreach ( $args['taxonomy'] as $taxonomy ) { 
  27. if ( ! taxonomy_exists( $taxonomy ) ) { 
  28. return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); 
  29.  
  30. $terms = $term_query->query( $args ); 
  31.  
  32. // Count queries are not filtered, for legacy reasons. 
  33. if ( ! is_array( $terms ) ) { 
  34. return $terms; 
  35.  
  36. /** 
  37. * Filters the found terms. 
  38. * @since 2.3.0 
  39. * @since 4.6.0 Added the `$term_query` parameter. 
  40. * @param array $terms Array of found terms. 
  41. * @param array $taxonomies An array of taxonomies. 
  42. * @param array $args An array of get_terms() arguments. 
  43. * @param WP_Term_Query $term_query The WP_Term_Query object. 
  44. */ 
  45. return apply_filters( 'get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query );