WordPress Get Category Information

Author: ICai
Date: 2024-06-30
Category: WordPress Development

00. Function Introduction

get_categories() is a core function provided by WordPress, used to retrieve defined categories in the website. It returns an array containing various information about the categories, such as category name, ID, description, etc.

Function Prototype

get_categories( string|array $args = '' ): array

• Official Documentation: developer.wordpress.org/reference/functions/get_categories/

01. Function Parameters

This function accepts an array as the $args parameter to filter and sort the category results. Common parameter configurations are as follows:

$args = array(
    'taxonomy'               => null,    // Taxonomy type, defaults to 'category' (only used if custom taxonomies are registered).
    'object_ids'             => null,    // Object ID (corresponds to ID in wp_posts table), used to get categories for specific posts.
    'orderby'                => 'name',  // Sort by. Options: 'name', 'slug', 'term_group', 'term_id', 'id', 'description', 'parent', 'term_order'
    'order'                  => 'ASC',   // Sort order: 'ASC' (ascending) or 'DESC' (descending)
    'hide_empty'             => true,    // Whether to hide empty categories (categories with no posts)
    'include'                => array(), // Array of category IDs to include
    'exclude'                => array(), // Array of category IDs to exclude
    'exclude_tree'           => array(), // Array of category IDs to exclude along with their children
    'number'                 => '',      // Limit the number of results returned
    'offset'                 => '',      // Offset for pagination
    'fields'                 => 'all',   // Fields to retrieve
    'count'                  => false,   // Whether to return the number of terms found
    'name'                   => '',      // Get category by name
    'slug'                   => '',      // Get category by slug
    'term_taxonomy_id'       => '',      // Get category by term_taxonomy_id
    'hierarchical'           => true,    // Whether to include terms that have non-empty descendants
    'search'                 => '',      // Search criteria
    'name__like'             => '',      // Match category names containing this string
    'description__like'      => '',      // Match category descriptions containing this string
    'pad_counts'             => false,   // Whether to include children's post counts in the parent's count
    'get'                    => '',      // String
    'child_of'               => 0,       // Get children of a specific category (and their children)
    'parent'                 => '',      // Get direct children of a specific category
    'childless'              => false,   // True to limit results to terms that have no children
    'cache_domain'           => 'core',  // Unique cache key to use when storing this query in the object cache
    'cache_results'          => true,    // Whether to cache term information
    'update_term_meta_cache' => true,    // Whether to prime meta cache for matched terms
    'meta_query'             => '',      // Meta data query
    'meta_key'               => '',      // Meta data key
    'meta_value'             => '',      // Meta data value
    'meta_type'              => '',      // MySQL data type to cast the meta_value to
    'meta_compare'           => '',      // MySQL operator for comparing the meta value
);

• Parameter Details: WP_Term_Query::__construct()

02. Return Value

Upon success, the function returns an array of WP_Term objects.

Example Return Structure:

Array
(
    [0] => WP_Term Object
        (
            [term_id] => 6
            [name] => Example
            [slug] => sample
            [term_group] => 0
            [term_taxonomy_id] => 6
            [taxonomy] => category
            [description] => 
            [parent] => 0
            [count] => 0
            [filter] => raw
            [cat_ID] => 6
            [category_count] => 0
            [category_description] => 
            [cat_name] => Example
            [category_nicename] => sample
            [category_parent] => 0
        )
    // ...
)

03. Basic Example

Below is a basic example of retrieving all top-level categories and outputting their names:

<?php

$categories = get_categories( array(
    'orderby' => 'name',
    'parent'  => 0
) );
 
foreach ( $categories as $category ) {
   echo '<p>' . $category->name . '</p>';
}

?>