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

Description

Compatibility

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

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 value

string

Category list for a post.

Performance profile

How much work a call to get_the_category_list() 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 get_post().

Scaling

Scales with input

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

Instructions

19–47

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

Plugin surface

2 hooks

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

Called by

9

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

What it touches

• hookthird-party callbacksapply_filters()called directly
• querycontent queryget_post()one call below get_the_category_list()

Further down the call graph this can also reach cache, option, 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 · 4 distinct outcomes

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

Hooks and filters 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 code

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	/**

Changelog

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.