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

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.

The ‘get_terms_fields’ filter passes the fields for the SELECT query along with the $args array.

The list of arguments that $args can contain, which will overwrite the defaults:

orderby – Default is ‘name’. Can be name, count, term_group, slug or nothing (will use term_id), Passing a custom value other than these will cause it to order based on the custom value.

order – Default is ASC. Can use DESC.

hide_empty – Default is true. Will not return empty terms, which means terms whose count is 0 according to the given taxonomy.

exclude – Default is an empty array. An array, comma- or space-delimited string of term ids to exclude from the return array. If ‘include’ is non-empty, ‘exclude’ is ignored.

exclude_tree – Default is an empty array. An array, comma- or space-delimited string of term ids to exclude from the return array, along with all of their descendant terms according to the primary taxonomy. If ‘include’ is non-empty, ‘exclude_tree’ is ignored.

include – Default is an empty array. An array, comma- or space-delimited string of term ids to include in the return array.

number – The maximum number of terms to return. Default is to return them all.

offset – The number by which to offset the terms query.

fields – Default is ‘all’, which returns an array of term objects. If ‘fields’ is ‘ids’ or ‘names’, returns an array of integers or strings, respectively.

slug – Returns terms whose “slug” matches this value. Default is empty string.

hierarchical – Whether to include terms that have non-empty descendants (even if ‘hide_empty’ is set to true).

search – Returned terms’ names will contain the value of ‘search’, case-insensitive. Default is an empty string.

name__like – Returned terms’ names will contain the value of ‘name__like’, case-insensitive. Default is empty string.

description__like – Returned terms’ descriptions will contain the value of ‘description__like’, case-insensitive. Default is empty string.

The argument ‘pad_counts’, if set to true will include the quantity of a term’s children in the quantity of each term’s “count” object variable.

The ‘get’ argument, if set to ‘all’ instead of its default empty string, returns terms regardless of ancestry or whether the terms are empty.

The ‘child_of’ argument, when used, should be set to the integer of a term ID. Its default is 0. If set to a non-zero value, all returned terms will be descendants of that term according to the given taxonomy. Hence ‘child_of’ is set to 0 if more than one taxonomy is passed in $taxonomies, because multiple taxonomies make term ancestry ambiguous.

The ‘parent’ argument, when used, should be set to the integer of a term ID. Its default is the empty string ”, which has a different meaning from the integer 0. If set to an integer value, all returned terms will have as an immediate ancestor the term whose ID is specified by that integer according to the given taxonomy. The ‘parent’ argument is different from ‘child_of’ in that a term X is considered a ‘parent’ of term Y only if term X is the father of term Y, not its grandfather or great-grandfather, etc.

The ‘cache_domain’ argument enables a unique cache key to be produced when this query is stored in object cache. For instance, if you are using one of this function’s filters to modify the query (such as ‘terms_clauses’), setting ‘cache_domain’ to a unique value will not overwrite the cache for similar queries. Default value is ‘core’.

Signature

get_terms( $taxonomies, $args = '' )
taxonomies
 (string|array) Taxonomy name or list of Taxonomy names
args
 (string|array) The values of what to search for when returning terms
Default: ''

Return

(array|WP_Error) List of Term Objects and their children. Will return WP_Error, if any of $taxonomies do not exist.

Source

function get_terms($taxonomies, $args = '') {
	global $wpdb;
	$empty_array = array();

	$single_taxonomy = ! is_array( $taxonomies ) || 1 === count( $taxonomies );
	if ( ! is_array( $taxonomies ) )
		$taxonomies = array( $taxonomies );

	foreach ( $taxonomies as $taxonomy ) {
		if ( ! taxonomy_exists($taxonomy) ) {
			$error = new WP_Error('invalid_taxonomy', __('Invalid taxonomy'));
			return $error;
		}
	}

	$defaults = array('orderby' => 'name', 'order' => 'ASC',
		'hide_empty' => true, 'exclude' => array(), 'exclude_tree' => array(), 'include' => array(),
		'number' => '', 'fields' => 'all', 'slug' => '', 'parent' => '',
		'hierarchical' => true, 'child_of' => 0, 'get' => '', 'name__like' => '', 'description__like' => '',
		'pad_counts' => false, 'offset' => '', 'search' => '', 'cache_domain' => 'core' );
270 more lines...
WP Trac GitHub

Link here