get_terms( array|string $args = array(), array|string $deprecated = '' ): WP_Term[]|int[]|string[]|string|WP_Error

Description

$terms = get_terms( array(
 'taxonomy' => 'post_tag',
 'hide_empty' => false,
) );

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

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 value

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.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

$terms = get_terms(
	array(
		'taxonomy'   => array( 'category', 'post_tag' ),
		'hide_empty' => false,
	)
);

if ( is_wp_error( $terms ) ) {
	echo esc_html( $terms->get_error_message() );
} else {
	foreach ( $terms as $term ) {
		echo esc_html( $term->taxonomy . ': ' . $term->name . ' (' . $term->count . ')' ) . '<br>';
	}
}

$categories = get_terms(
	'category',
	array(
		'hide_empty' => false,
		'orderby'    => 'name',
	)
);

if ( is_wp_error( $categories ) ) {
	echo esc_html( $categories->get_error_message() );
} else {
	foreach ( $categories as $category ) {
		echo esc_html( $category->name ) . '<br>';
	}
}

Common problems and fixes · 4

• Why does get_terms() come back empty even though I created the terms?
• Why did get_terms() return a WP_Error instead of a list of terms?
• Why doesn't my 'get_terms' filter callback ever run?
• Why did an array I passed as the first argument get treated as a list of taxonomies instead of as $args?

Alternatives and related functions

get_term

When you already know a single term's ID and just need that one term object instead of running a query.

wp_get_post_terms

When you need the terms assigned to one specific post rather than every term in a taxonomy.

get_categories

When you specifically want category terms and prefer a shorthand wrapper instead of setting 'taxonomy' yourself.

WP_Term_Query

When you want direct access to the query object, for example to inspect query_vars or reuse the same query multiple times.

Performance profile

How much work a call to get_terms() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->query().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

38–63

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 87.

Plugin surface

1 hook

Third-party callbacks on 'get_terms' run inside this call, and their cost is not bounded by anything here.

Called by

33

33 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• querycontent queryget_terms()this function does it
• hookthird-party callbacksapply_filters()called directly
• sqldatabase query->query()called directly

Further down the call graph this can also reach option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 3 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost get_terms() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 1

One hook fires while get_terms() runs, in this order:

1. 1
   apply_filters( get_terms )filterline 1379 (+63 into the body)

   Filters the found terms.

Uses · 6

• wp_parse_args()Merges user defined arguments into defaults array.
• taxonomy_exists()Determines whether the taxonomy name exists.
• __()Retrieves the translation of $text.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• WP_Term_Query::__construct()Constructor.
• WP_Error::__construct()Initializes the error.

Used by · 33

• WP_Customize_Nav_Menus::load_available_items_query()Performs the post_type and taxonomy queries for loading available menu items.
• WP_Customize_Nav_Menus::search_available_items_query()Performs post queries for available-item searching.
• WP_Posts_List_Table::formats_dropdown()Displays a formats drop-down for filtering items.
• WP_REST_Terms_Controller::get_items()Retrieves terms associated with a taxonomy.
• WP_Term_Query::get_terms()Retrieves the query results.
• WP_Terms_List_Table::prepare_items()
• WP_Widget_Links::form()Outputs the settings form for the Links widget.
• Walker_Category::start_el()Starts the element output.
• _get_term_hierarchy()Retrieves children of taxonomy as term IDs.
• _wp_ajax_menu_quick_search()Prints the appropriate response to a menu quick search.
• export_wp()Generates the WXR export file for download.
• get_all_category_ids()Retrieves all category IDs.

Source code

View on Trac ↗View on GitHub ↗

1316function get_terms( $args = array(), $deprecated = '' ) {1317	$term_query = new WP_Term_Query();1318 1319	$defaults = array(1320		'suppress_filter' => false,1321	);1322 1323	/*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 );1333 1334	if ( $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 );1340		if ( isset( $args['taxonomy'] ) && null !== $args['taxonomy'] ) {1341			$args['taxonomy'] = (array) $args['taxonomy'];1342		}1343	}1344 1345	if ( ! empty( $args['taxonomy'] ) ) {1346		foreach ( $args['taxonomy'] as $taxonomy ) {1347			if ( ! taxonomy_exists( $taxonomy ) ) {1348				return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );1349			}1350		}1351	}1352 1353	// Don't pass suppress_filter to WP_Term_Query.1354	$suppress_filter = $args['suppress_filter'];1355	unset( $args['suppress_filter'] );1356 1357	$terms = $term_query->query( $args );1358 1359	// Count queries are not filtered, for legacy reasons.1360	if ( ! is_array( $terms ) ) {1361		return $terms;1362	}1363 1364	if ( $suppress_filter ) {1365		return $terms;1366	}1367 1368	/**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	 */1379	return apply_filters( 'get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query );1380}

Changelog

Introduced in 4.8.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.8.8 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.