WordPress get_terms() Function [Tutorial]

WordPress, a widely used content management system, offers a wide range of features that facilitate data manipulation and retrieval for developers. Among these features, get_terms() stands out as a highly effective function for retrieving taxonomy terms in WordPress. This article aims to thoroughly examine the capabilities of get_terms(), including its syntax, parameters, and practical uses.

The get_terms() Function

Let’s take a look at the get_terms() function:

<?php

get_terms(array|string $args = [], array|string $deprecated = '');

Here, $args is an array or string of arguments that customize the query, and $deprecated is an optional parameter that is no longer recommended for use. Let’s explore the essential parameters within the $args array:

1. $taxonomy (string|string[]): Taxonomy name, or array of taxonomy names, to which results should be limited.
2. $object_ids (int|int[]): Object ID, or array of object IDs. Results will be limited to terms associated with these objects.
3. $orderby (string): Field(s) to order terms by. Accepts various options such as ‘name’, ‘slug’, ‘term_group’, ‘term_id’, ‘id’, ‘description’, ‘parent’, ‘term_order’, ‘count’, ‘include’, ‘slug__in’, ‘meta_value’, ‘meta_value_num’, the value of $meta_key, the array keys of $meta_query, and ‘none’. Default ‘name’.
4. $order (string): Whether to order terms in ascending or descending order. Accepts ‘ASC’ (ascending) or ‘DESC’ (descending). Default ‘ASC’.
5. $hide_empty (bool|int): Whether to hide terms not assigned to any posts. Accepts 1|true or 0|false. Default 1|true.
6. $include (int[]|string): Array or comma/space-separated string of term IDs to include. Default empty array.
7. $exclude (int[]|string): Array or comma/space-separated string of term IDs to exclude. If $include is non-empty, $exclude is ignored. Default empty array.
8. $exclude_tree (int[]|string): 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. Default empty array.
9. $number (int|string): Maximum number of terms to return. Accepts ”|0 (all) or any positive number. Default ”|0 (all).
10. $offset (int): The number by which to offset the terms query. Default empty.
11. $fields (string): Term fields to query for. Accepts options like ‘all’, ‘all_with_object_id’, ‘ids’, ‘tt_ids’, ‘names’, ‘slugs’, ‘count’, ‘id=>parent’, ‘id=>name’, ‘id=>slug’. Default ‘all’.
12. $count (bool): Whether to return a term count. If true, will take precedence over $fields. Default false.
13. $name (string|string[]): Name or array of names to return term(s) for. Default empty.
14. $slug (string|string[]): Slug or array of slugs to return term(s) for. Default empty.
15. $term_taxonomy_id (int|int[]): Term taxonomy ID, or array of term taxonomy IDs, to match when querying terms.
16. $hierarchical (bool): Whether to include terms that have non-empty descendants (even if $hide_empty is set to true). Default true.
17. $search (string): Search criteria to match terms. Will be SQL-formatted with wildcards before and after. Default empty.
18. $name__like (string): Retrieve terms with criteria by which a term is LIKE $name__like. Default empty.
19. $description__like (string): Retrieve terms where the description is LIKE $description__like. Default empty.
20. $pad_counts (bool): Whether to pad the quantity of a term’s children in the quantity of each term’s “count” object variable. Default false.
21. $get (string|string[]): Whether to return terms regardless of ancestry or whether the terms are empty. Accepts ‘all’ or ” (disabled). Default ”.
22. $child_of (int): Term ID to retrieve child terms of. If multiple taxonomies are passed, $child_of is ignored. Default 0.
23. $parent (int): Parent term ID to retrieve direct-child terms of. Default empty.
24. $childless (bool): True to limit results to terms that have no children. This parameter has no effect on non-hierarchical taxonomies. Default false.
25. $cache_domain (string): Unique cache key to be produced when this query is stored in an object cache. Default ‘core’.
26. $cache_results (bool): Whether to cache term information. Default true.
27. $update_term_meta_cache (bool): Whether to prime meta caches for matched terms. Default true.
28. $meta_key (string|string[]): Meta key or keys to filter by.
29. $meta_value (string|string[]): Meta value or values to filter by.
30. $meta_compare (string): MySQL operator used for comparing the meta value. See WP_Meta_Query::__construct() for accepted values and the default value.
31. $meta_compare_key (string): MySQL operator used for comparing the meta key. See WP_Meta_Query::__construct() for accepted values and the default value.
32. $meta_type (string): MySQL data type that the meta_value column will be CAST to for comparisons. See WP_Meta_Query::__construct() for accepted values and the default value.
33. $meta_type_key (string): MySQL data type that the meta_key column will be CAST to for comparisons. See WP_Meta_Query::__construct() for accepted values and the default value.
34. $meta_query (array): An associative array of WP_Meta_Query arguments. See WP_Meta_Query::__construct() for accepted values.

Practical Applications

Now that we understand the syntax and parameters of get_terms(), let’s explore some practical applications.

1. Displaying a List of Categories or Tags

<?php

$categories = get_terms( 'category' );
foreach ( $categories as $category ) {
    echo '<a href="' . get_term_link( $category ) . '">' . $category->name . '</a>';
}

This example retrieves and displays a list of categories with links to their respective archive pages.

2. Custom Queries with Additional Parameters

<?php

$args = array(
    'taxonomy'   => 'post_tag',
    'hide_empty' => false,
    'orderby'    => 'count',
    'order'      => 'DESC',
);
$popular_tags = get_terms($args);

Here, we customize the query to retrieve popular tags by setting the orderby parameter to ‘count’ and ordering them in descending order.

3. Excluding Specific Terms

<?php

$args = array(
    'taxonomy' => 'category',
    'exclude'  => [1, 3, 5],
);
$categories = get_terms($args);

In this example, the function retrieves categories while excluding specific term IDs.

Conclusion

The get_terms() function within WordPress serves as a potent resource for developers seeking to access and manipulate taxonomy terms. By comprehending its syntax and parameters, one can customize queries to meet specific requirements, thereby making it an invaluable asset for constructing dynamic and personalized websites. Whether the objective is to create a bespoke navigation menu, showcase a tag cloud, or implement a distinctive taxonomy-related feature, get_terms() unlocks a plethora of possibilities in WordPress development.