get_term_parents_list() │ WP 4.8.0

Gets the list of parents of the specified term (taxonomy element).

As a result we get text or links separated by the specified separator (comma, slash).

Uses: get_ancestors()
Used By: get_category_parents()
1 time — 0.003063 sec (very slow) | 50000 times — 14.40 sec (slow) | PHP 7.1.2, WP 4.8

No Hooks.

Return

String|WP_Error.

  • A string containing term slugs or names separated by a comma. Or HTML code with term links anchored with term names.
  • An empty string if no term exists.
  • WP_Error if such taxonomy NOT exists.

Usage

get_term_parents_list( $term_id, $taxonomy, $args );
$term_id(int) (required)
Term ID.
$taxonomy(string) (required)
Taxonomy name.
$args(string|array)

Array of optional arguments. By default it looks like this:

$defaults = [
	'format'    => 'name',
	'separator' => '/',
	'link'      => true,
	'inclusive' => true,
];

Default: array() - presets

  • format(string)
    Use term names or slugs for display. Accepts:.

    • 'name' - displays the names of the terms.
    • 'slug' - displays the slugs of terms.
      Default: 'name'

  • separator(string)
    Separator between names or links (if the link parameter is set).
    Default: '/'

  • link(true|false)
    Whether to format as a link.

    • true - output the names as links to the terms.
    • false - output the names as plain text.
      Default: true
  • inclusive(true|false)
    Include the term to get the parents for.
    Default: true

Examples

0

#1 Get a list of parent elements of the taxonomy term

This example outputs the "breadcrumbs" for the term 593 (categories). The element itself is also included in the link chain.

echo get_term_parents_list( 593, 'wpfunccat', [
	'separator' => ' / ',
] );

/*
<a href="/function-cat/taxonomy">Taxonomy</a> /
<a href="/function-cat/categories">Categories</a> /
*/

1.2) If link = false is specified in the parameters

echo get_term_parents_list( 593, 'wpfunccat', array(
	'separator' => ' / ',
	'link' => false,
) );

/*
Taxonomies / Categories /
*/

1.3) If you specify format = 'slug' in the parameters

echo get_term_parents_list( 593, 'wpfunccat', array(
	'separator' => ' / ',
	'format' => 'slug',
	'link' => false,
) );

/*
taxonomy / categories
*/

Changelog

Since 4.8.0 Introduced.

get_term_parents_list() code WP 6.5.2

wp-includes/category-template.php 
function get_term_parents_list( $term_id, $taxonomy, $args = array() ) {
	$list = '';
	$term = get_term( $term_id, $taxonomy );

	if ( is_wp_error( $term ) ) {
		return $term;
	}

	if ( ! $term ) {
		return $list;
	}

	$term_id = $term->term_id;

	$defaults = array(
		'format'    => 'name',
		'separator' => '/',
		'link'      => true,
		'inclusive' => true,
	);

	$args = wp_parse_args( $args, $defaults );

	foreach ( array( 'link', 'inclusive' ) as $bool ) {
		$args[ $bool ] = wp_validate_boolean( $args[ $bool ] );
	}

	$parents = get_ancestors( $term_id, $taxonomy, 'taxonomy' );

	if ( $args['inclusive'] ) {
		array_unshift( $parents, $term_id );
	}

	foreach ( array_reverse( $parents ) as $term_id ) {
		$parent = get_term( $term_id, $taxonomy );
		$name   = ( 'slug' === $args['format'] ) ? $parent->slug : $parent->name;

		if ( $args['link'] ) {
			$list .= '<a href="' . esc_url( get_term_link( $parent->term_id, $taxonomy ) ) . '">' . $name . '</a>' . $args['separator'];
		} else {
			$list .= $name . $args['separator'];
		}
	}

	return $list;
}

List (wp_list)

Taxonomies (Categories, Tags)