get_term_link( WP_Term|int|string $term, string $taxonomy = '' ): string|WP_Error

Compatibility

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

Parameters

$termWP_Term|int|string

The term object, ID, or slug whose link will be retrieved.

$taxonomystringoptional

Taxonomy. Default empty.Default: ''

Return value

string|WP_Error

URL of the taxonomy term archive on success, WP_Error if term does not exist.

Performance profile

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

Scaling

Scales with input

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

Instructions

12–103

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

Plugin surface

4 hooks

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

Called by

18

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

What it touches

• querycontent queryget_term()called directly
• hookthird-party callbacksapply_filters()called directly

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

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

Hooks and filters fired · 4

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

1. 1
   apply_filters( pre_term_link )filterline 4664 (+31 into the body)

   Filters the permalink structure for a term before token replacement occurs.

2. 2
   apply_filters( tag_link )filterline 4708 (+75 into the body)

   Filters the tag link.

3. 3
   apply_filters( category_link )filterline 4721 (+88 into the body)

   Filters the category link.

4. 4
   apply_filters( term_link )filterline 4733 (+100 into the body)

   Filters the term link.

Uses · 10

• get_term()Gets all term data from database by term ID.
• get_term_by()Gets all term data from database by term field and data.
• __()Retrieves the translation of $text.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_taxonomy()Retrieves the taxonomy object of $taxonomy.
• home_url()Retrieves the URL for the current site where the front end is accessible.
• get_ancestors()Gets an array of ancestor IDs for a given object.
• user_trailingslashit()Retrieves a trailing-slashed string if the site is set for adding trailing slashes.
• WP_Error::__construct()Initializes the error.

Used by · 18

• WP_Customize_Nav_Menu_Item_Setting::value_as_wp_post_nav_menu_item()Get the value emulated into a WP_Post and set up as a nav_menu_item.
• WP_Customize_Nav_Menus::load_available_items_query()Performs the post_type and taxonomy queries for loading available menu items.
• WP_Customize_Nav_Menus::search_available_items_query()Performs post queries for available-item searching.
• WP_REST_Term_Search_Handler::prepare_item()Prepares the search result for a given term ID.
• WP_REST_Terms_Controller::prepare_item_for_response()Prepares a single term output for response.
• WP_Sitemaps_Taxonomies::get_url_list()Gets a URL list for a taxonomy sitemap.
• WP_Terms_List_Table::handle_row_actions()Generates and displays row action links.
• Walker_Category::start_el()Starts the element output.
• get_category_link()Retrieves category link URL.
• get_post_format_link()Returns a link to a post format index.
• get_term_feed_link()Retrieves the feed link for a term.
• get_term_parents_list()Retrieves term parents with separator.

Source code

View on Trac ↗View on GitHub ↗

4633function get_term_link( $term, $taxonomy = '' ) {4634	global $wp_rewrite;4635 4636	if ( ! is_object( $term ) ) {4637		if ( is_int( $term ) ) {4638			$term = get_term( $term, $taxonomy );4639		} else {4640			$term = get_term_by( 'slug', $term, $taxonomy );4641		}4642	}4643 4644	if ( ! is_object( $term ) ) {4645		$term = new WP_Error( 'invalid_term', __( 'Empty Term.' ) );4646	}4647 4648	if ( is_wp_error( $term ) ) {4649		return $term;4650	}4651 4652	$taxonomy = $term->taxonomy;4653 4654	$termlink = $wp_rewrite->get_extra_permastruct( $taxonomy );4655 4656	/**4657	 * Filters the permalink structure for a term before token replacement occurs.4658	 *4659	 * @since 4.9.04660	 *4661	 * @param string  $termlink The permalink structure for the term's taxonomy.4662	 * @param WP_Term $term     The term object.4663	 */4664	$termlink = apply_filters( 'pre_term_link', $termlink, $term );4665 4666	$slug = $term->slug;4667	$t    = get_taxonomy( $taxonomy );4668 4669	if ( empty( $termlink ) ) {4670		if ( 'category' === $taxonomy ) {4671			$termlink = '?cat=' . $term->term_id;4672		} elseif ( $t->query_var ) {4673			$termlink = "?$t->query_var=$slug";4674		} else {4675			$termlink = "?taxonomy=$taxonomy&term=$slug";4676		}4677		$termlink = home_url( $termlink );4678	} else {4679		if ( ! empty( $t->rewrite['hierarchical'] ) ) {4680			$hierarchical_slugs = array();4681			$ancestors          = get_ancestors( $term->term_id, $taxonomy, 'taxonomy' );4682			foreach ( (array) $ancestors as $ancestor ) {4683				$ancestor_term        = get_term( $ancestor, $taxonomy );4684				$hierarchical_slugs[] = $ancestor_term->slug;4685			}4686			$hierarchical_slugs   = array_reverse( $hierarchical_slugs );4687			$hierarchical_slugs[] = $slug;4688			$termlink             = str_replace( "%$taxonomy%", implode( '/', $hierarchical_slugs ), $termlink );4689		} else {4690			$termlink = str_replace( "%$taxonomy%", $slug, $termlink );4691		}4692		$termlink = home_url( user_trailingslashit( $termlink, 'category' ) );4693	}4694 4695	// Back compat filters.4696	if ( 'post_tag' === $taxonomy ) {4697 4698		/**4699		 * Filters the tag link.4700		 *4701		 * @since 2.3.04702		 * @since 2.5.0 Deprecated in favor of {@see 'term_link'} filter.4703		 * @since 5.4.1 Restored (un-deprecated).4704		 *4705		 * @param string $termlink Tag link URL.4706		 * @param int    $term_id  Term ID.4707		 */4708		$termlink = apply_filters( 'tag_link', $termlink, $term->term_id );4709	} elseif ( 'category' === $taxonomy ) {4710 4711		/**4712		 * Filters the category link.

Changelog

Introduced in 2.5.0. Unchanged from 6.7.7 through 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 6.7.7 tag, from src/wp-includes/taxonomy.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.