get_the_category_list() WordPress Function

The get_the_category_list() function is a built-in function in WordPress that can be used to retrieve a list of all the categories for a given post.

get_the_category_list( string $separator = '', string $parents = '', int $post_id = false ) #

Retrieves category list for a post in either HTML list or custom format.

Description
- See also
Parameters
Return
Source
Related
- Uses
- Used By
Changelog

Description

Generally used for quick, delimited (e.g. comma-separated) lists of categories, as part of a post entry meta.

For a more powerful, list-based function, see wp_list_categories().

Top ↑

Parameters

$separator

(string)(Optional) Separator between the categories. By default, the links are placed in an unordered list. An empty string will result in the default behavior.

Default value: ''

$parents

(string)(Optional) How to display the parents.

Default value: ''

$post_id

(int)(Optional) Post ID to retrieve categories.

Default value: false

Top ↑

Return

(string) Category list for a post.

Top ↑

Source

File: wp-includes/category-template.php

function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
    global $wp_rewrite;
 
    if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
        /** This filter is documented in wp-includes/category-template.php */
        return apply_filters( 'the_category', '', $separator, $parents );
    }
 
    /**
     * Filters the categories before building the category list.
     *
     * @since 4.4.0
     *
     * @param WP_Term[] $categories An array of the post's categories.
     * @param int|bool  $post_id    ID of the post we're retrieving categories for.
     *                              When `false`, we assume the current post in the loop.
     */
    $categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );
 
    if ( empty( $categories ) ) {
        /** This filter is documented in wp-includes/category-template.php */
        return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
    }
 
    $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
 
    $thelist = '';
    if ( '' === $separator ) {
        $thelist .= '<ul class="post-categories">';
        foreach ( $categories as $category ) {
            $thelist .= "\n\t<li>";
            switch ( strtolower( $parents ) ) {
                case 'multiple':
                    if ( $category->parent ) {
                        $thelist .= get_category_parents( $category->parent, true, $separator );
                    }
                    $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>';
                    break;
                case 'single':
                    $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '"  ' . $rel . '>';
                    if ( $category->parent ) {
                        $thelist .= get_category_parents( $category->parent, false, $separator );
                    }
                    $thelist .= $category->name . '</a></li>';
                    break;
                case '':
                default:
                    $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>';
            }
        }
        $thelist .= '</ul>';
    } else {
        $i = 0;
        foreach ( $categories as $category ) {
            if ( 0 < $i ) {
                $thelist .= $separator;
            }
            switch ( strtolower( $parents ) ) {
                case 'multiple':
                    if ( $category->parent ) {
                        $thelist .= get_category_parents( $category->parent, true, $separator );
                    }
                    $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>';
                    break;
                case 'single':
                    $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>';
                    if ( $category->parent ) {
                        $thelist .= get_category_parents( $category->parent, false, $separator );
                    }
                    $thelist .= "$category->name</a>";
                    break;
                case '':
                default:
                    $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>';
            }
            ++$i;
        }
    }
 
    /**
     * Filters the category or list of categories.
     *
     * @since 1.2.0
     *
     * @param string $thelist   List of categories for the current post.
     * @param string $separator Separator used between the categories.
     * @param string $parents   How to display the category parents. Accepts 'multiple',
     *                          'single', or empty.
     */
    return apply_filters( 'the_category', $thelist, $separator, $parents );
}

Expand full source code Collapse full source codeView on TracView on GitHub

Top ↑

Uses

Uses
Uses	Description
wp-includes/category-template.php:the_category_list	Filters the categories before building the category list.
wp-includes/category-template.php:get_the_category()	Retrieves post categories.
wp-includes/category-template.php:get_category_parents()	Retrieves category parents with separator.
wp-includes/category-template.php:get_category_link()	Retrieves category link URL.
wp-includes/category-template.php:the_category	Filters the category or list of categories.
wp-includes/l10n.php:__()	Retrieve the translation of $text.
wp-includes/formatting.php:esc_url()	Checks and cleans a URL.
wp-includes/taxonomy.php:is_object_in_taxonomy()	Determines if the given object type is associated with the given taxonomy.
wp-includes/plugin.php:apply_filters()	Calls the callback functions that have been added to a filter hook.
wp-includes/post.php:get_post_type()	Retrieves the post type of the current post or of a given post.
wp-includes/class-wp-rewrite.php:WP_Rewrite::using_permalinks()	Determines whether permalinks are being used.