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

Description

Parameters

$separatorstringoptional

Separator between the categories. By default, the links are placed in an unordered list. An empty string will result in the default behavior.Default: ''

$parentsstringoptional

How to display the parents. Accepts 'multiple', 'single', or empty. Default empty string.Default: ''

$post_idint|falseoptional

ID of the post to retrieve categories for. Defaults to the current post.Default: false

Return

string

Category list for a post.

Hooks fired · 4

4 hooks fire while get_the_category_list() runs, in this order:

1. 1
   apply_filters( the_category )filterline 146 (+5 into the body)

   Filters the category or list of categories.

2. 2
   apply_filters( the_category_list )filterline 158 (+17 into the body)

   Filters the categories before building the category list.

3. 3
   apply_filters( the_category )filterline 162 (+21 into the body)

   Filters the category or list of categories.

4. 4
   apply_filters( the_category )filterline 230 (+89 into the body)

   Filters the category or list of categories.

Uses · 8

• is_object_in_taxonomy()Determines if the given object type is associated with the given taxonomy.
• get_post_type()Retrieves the post type of the current post or of a given post.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_the_category()Retrieves post categories.
• __()Retrieves the translation of $text.
• get_category_parents()Retrieves category parents with separator.
• esc_url()Checks and cleans a URL.
• get_category_link()Retrieves category link URL.

Used by · 9

• the_category()Displays category list for a post in either HTML list or custom format.
• twenty_twenty_one_entry_meta_footer()Prints HTML with meta information for the categories, tags and comments.
• twentyfifteen_entry_meta()Prints HTML with meta information for the categories, tags.
• twentynineteen_entry_footer()Prints HTML with meta information for the categories, tags and comments.
• twentyseventeen_entry_footer()Prints HTML with meta information for the categories, tags and comments.
• twentysixteen_entry_taxonomies()Prints HTML with category and tags for current post.
• twentyten_posted_in()Prints HTML with meta information for the current post (category, tags and permalink).
• twentythirteen_entry_meta()Prints HTML with meta information for current post: categories, tags, permalink, author, and date.
• twentytwelve_entry_meta()Sets up post entry meta.

Source

View on Trac ↗View on GitHub ↗

141function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {142	global $wp_rewrite;143 144	if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {145		/** This filter is documented in wp-includes/category-template.php */146		return apply_filters( 'the_category', '', $separator, $parents );147	}148 149	/**150	 * Filters the categories before building the category list.151	 *152	 * @since 4.4.0153	 *154	 * @param WP_Term[] $categories An array of the post's categories.155	 * @param int|false $post_id    ID of the post to retrieve categories for.156	 *                              When `false`, defaults to the current post in the loop.157	 */158	$categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );159 160	if ( empty( $categories ) ) {161		/** This filter is documented in wp-includes/category-template.php */162		return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );163	}164 165	$rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';166 167	$thelist = '';168	if ( '' === $separator ) {169		$thelist .= '<ul class="post-categories">';170		foreach ( $categories as $category ) {171			$thelist .= "\n\t<li>";172			switch ( strtolower( $parents ) ) {173				case 'multiple':174					if ( $category->parent ) {175						$thelist .= get_category_parents( $category->parent, true, $separator );176					}177					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>';178					break;179				case 'single':180					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '"  ' . $rel . '>';181					if ( $category->parent ) {182						$thelist .= get_category_parents( $category->parent, false, $separator );183					}184					$thelist .= $category->name . '</a></li>';185					break;186				case '':187				default:188					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>';189			}190		}191		$thelist .= '</ul>';192	} else {193		$i = 0;194		foreach ( $categories as $category ) {195			if ( 0 < $i ) {196				$thelist .= $separator;197			}198			switch ( strtolower( $parents ) ) {199				case 'multiple':200					if ( $category->parent ) {201						$thelist .= get_category_parents( $category->parent, true, $separator );202					}203					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>';204					break;205				case 'single':206					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>';207					if ( $category->parent ) {208						$thelist .= get_category_parents( $category->parent, false, $separator );209					}210					$thelist .= "$category->name</a>";211					break;212				case '':213				default:214					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>';215			}216			++$i;217		}218	}219 220	/**

History

Introduced in 1.5.1. One change between 6.7.7 and 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 7.1.0 tag, from src/wp-includes/category-template.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.