get_term_parents_list( int $term_id, string $taxonomy, string|array $args = array() )

Retrieve term parents with separator.


Description Description


Parameters Parameters

$term_id

(int) (Required) Term ID.

$taxonomy

(string) (Required) Taxonomy name.

$args

(string|array) (Optional) Array of optional arguments.

  • 'format'
    (string) Use term names or slugs for display. Accepts 'name' or 'slug'. Default 'name'.
  • 'separator'
    (string) Separator for between the terms. Default '/'.
  • 'link'
    (bool) Whether to format as a link. Default true.
  • 'inclusive'
    (bool) Include the term to get the parents for. Default true.

Default value: array()


Top ↑

Return Return

(string|WP_Error) A list of term parents on success, WP_Error or empty string on failure.


Top ↑

Source Source

File: 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;
}

Top ↑

Changelog Changelog

Changelog
Version Description
4.8.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note content
    Contributed by keesiemeijer

    Example to display term parents in category archive pages. Use this in your category archive theme templates.

    <?php
    if ( is_category() ) {
    	// Get the current category term id.
    	$query_obj = get_queried_object();
    	$term_id   = $query_obj->term_id;
    
    	echo get_term_parents_list( $term_id, 'category' );
    }
    ?>
    

    This is an example of what it would print on a “Grandchild Category” term page.

    Parent Category/Child Category/Grandchild Category

  2. Skip to note content
    Contributed by keesiemeijer

    Example of a breadcrumb trail for taxonomy pages. Use it in your theme’s taxonomy templates

    <?php
    if ( ( is_tax() || is_category() || is_tag() ) ) {
    	$trail     = '';
    	$home      = '/<a href="' . get_home_url() . '">Home</a>';
    	$query_obj = get_queried_object();
    	$term_id   = $query_obj->term_id;
    	$taxonomy  = get_taxonomy( $query_obj->taxonomy );
    
    	if ( $term_id && $taxonomy ) {
    		// Add taxonomy label name to the trail.
    		$trail .=  '/' . $taxonomy->labels->menu_name;
    		// Add term parents to the trail.
    		$trail .= '/' . get_term_parents_list( $term_id, $taxonomy->name, array( 'inclusive' => false ) );
    	}
    
    	// Print trail and add current term name at the end.
    	echo '<p class="breadcrumb-trail">' . $home . $trail . $query_obj->name . '</p>';
    }
    ?>
    

You must log in before being able to contribute a note or feedback.