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

20

20 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 4697 (+31 into the body)

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

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

   Filters the tag link.

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

   Filters the category link.

4. 4
   apply_filters( term_link )filterline 4766 (+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 · 20

• 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.
• _block_bindings_term_data_get_value()Gets value for Term Data source.
• 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.

Source code

View on Trac ↗View on GitHub ↗

4666function get_term_link( $term, $taxonomy = '' ) {4667	global $wp_rewrite;4668 4669	if ( ! is_object( $term ) ) {4670		if ( is_int( $term ) ) {4671			$term = get_term( $term, $taxonomy );4672		} else {4673			$term = get_term_by( 'slug', $term, $taxonomy );4674		}4675	}4676 4677	if ( ! is_object( $term ) ) {4678		$term = new WP_Error( 'invalid_term', __( 'Empty Term.' ) );4679	}4680 4681	if ( is_wp_error( $term ) ) {4682		return $term;4683	}4684 4685	$taxonomy = $term->taxonomy;4686 4687	$termlink = $wp_rewrite->get_extra_permastruct( $taxonomy );4688 4689	/**4690	 * Filters the permalink structure for a term before token replacement occurs.4691	 *4692	 * @since 4.9.04693	 *4694	 * @param string  $termlink The permalink structure for the term's taxonomy.4695	 * @param WP_Term $term     The term object.4696	 */4697	$termlink = apply_filters( 'pre_term_link', $termlink, $term );4698 4699	$slug = $term->slug;4700	$t    = get_taxonomy( $taxonomy );4701 4702	if ( empty( $termlink ) ) {4703		if ( 'category' === $taxonomy ) {4704			$termlink = '?cat=' . $term->term_id;4705		} elseif ( $t->query_var ) {4706			$termlink = "?$t->query_var=$slug";4707		} else {4708			$termlink = "?taxonomy=$taxonomy&term=$slug";4709		}4710		$termlink = home_url( $termlink );4711	} else {4712		if ( ! empty( $t->rewrite['hierarchical'] ) ) {4713			$hierarchical_slugs = array();4714			$ancestors          = get_ancestors( $term->term_id, $taxonomy, 'taxonomy' );4715			foreach ( (array) $ancestors as $ancestor ) {4716				$ancestor_term        = get_term( $ancestor, $taxonomy );4717				$hierarchical_slugs[] = $ancestor_term->slug;4718			}4719			$hierarchical_slugs   = array_reverse( $hierarchical_slugs );4720			$hierarchical_slugs[] = $slug;4721			$termlink             = str_replace( "%$taxonomy%", implode( '/', $hierarchical_slugs ), $termlink );4722		} else {4723			$termlink = str_replace( "%$taxonomy%", $slug, $termlink );4724		}4725		$termlink = home_url( user_trailingslashit( $termlink, 'category' ) );4726	}4727 4728	// Back compat filters.4729	if ( 'post_tag' === $taxonomy ) {4730 4731		/**4732		 * Filters the tag link.4733		 *4734		 * @since 2.3.04735		 * @since 2.5.0 Deprecated in favor of {@see 'term_link'} filter.4736		 * @since 5.4.1 Restored (un-deprecated).4737		 *4738		 * @param string $termlink Tag link URL.4739		 * @param int    $term_id  Term ID.4740		 */4741		$termlink = apply_filters( 'tag_link', $termlink, $term->term_id );4742	} elseif ( 'category' === $taxonomy ) {4743 4744		/**4745		 * 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.9.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.