get_permalink( int|WP_Post $post = 0, bool $leavename = false ): string|false

Compatibility

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

Parameters

$postint|WP_Postoptional

Post ID or post object. Default is the global $post.Default: 0

$leavenamebooloptional

Whether to keep post name or page name. Default false.Default: false

Return value

string|false

The permalink URL. False if the post does not exist.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

$post_ids = array( 1, 2, 3, 4, 5 );

foreach ( $post_ids as $post_id ) {
	$post = get_post( $post_id );

	if ( ! $post ) {
		continue;
	}

	$permalink = get_permalink( $post_id );

	if ( $permalink ) {
		echo esc_html( $post->post_title ) . ': ' . esc_html( $permalink ) . "\n";
	} else {
		echo esc_html( $post->post_title ) . ': no permalink available' . "\n";
	}
}

$post = get_post( 2 );

$resolved = get_permalink( $post );
$template = get_permalink( $post, true );

printf( "Resolved: %s\n", esc_html( $resolved ) );
printf( "Template: %s\n", esc_html( $template ) );

Common problems and fixes · 4

• Why does get_permalink() return false?
• Why does get_permalink() keep returning a ?p=123 link instead of a pretty URL?
• Why does %category% in my permalink structure only show one term when a post has two categories?
• Do I need to escape the URL get_permalink() returns before echoing it?

Alternatives and related functions

get_the_permalink

When you're already inside The Loop and want the result passed through the 'the_permalink' filter that themes and plugins commonly hook into.

the_permalink

When you just want to echo the current post's permalink directly in a template without capturing it in a variable first.

get_post_permalink

When you specifically need the link for a custom post type and want to bypass the post_type-detection branching that get_permalink() does internally.

get_page_link

When you know in advance you're linking to a page rather than a post, so you can skip the post-type check get_permalink() performs before delegating to it.

Performance profile

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

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

28–182

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

Plugin surface

3 hooks

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

Called by

50

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

What it touches

• querycontent queryget_post()called directly
• optionoption read or writeget_option()called directly
• hookthird-party callbacksapply_filters()called directly
• cacheobject cachewp_cache_get()one call below get_permalink()
• serializeserialisationmaybe_unserialize()one call below get_permalink()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 52 distinct outcomes

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

Hooks and filters fired · 3

3 hooks fire while get_permalink() runs, in this order:

1. 1
   apply_filters( pre_post_link )filterline 217 (+47 into the body)

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

2. 2
   apply_filters( post_link_category )filterline 244 (+74 into the body)

   Filters the category that gets used in the %category% permalink token.

3. 3
   apply_filters( post_link )filterline 308 (+138 into the body)

   Filters the permalink for a post.

Uses · 17

• get_post()Retrieves post data given a post ID or post object.
• get_page_link()Retrieves the permalink for the current page or page ID.
• get_attachment_link()Retrieves the permalink for an attachment.
• get_post_types()Gets a list of all registered post type objects.
• get_post_permalink()Retrieves the permalink for a post of a custom post type.
• get_option()Retrieves an option value based on an option name.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_force_plain_post_permalink()Determine whether post should always use a plain permalink structure.
• str_contains()Polyfill for `str_contains()` function added in PHP 8.0.
• get_the_category()Retrieves post categories.
• wp_list_sort()Sorts an array of objects or arrays based on one or more orderby arguments.
• get_term()Gets all term data from database by term ID.

Used by · 50

• TwentyTwenty_Walker_Page::start_el()Outputs the beginning of the current element in the tree.
• Twenty_Eleven_Ephemera_Widget::widget()Outputs the HTML for this widget.
• Twenty_Fourteen_Ephemera_Widget::widget()Outputs the HTML for this widget.
• WP_Comments_List_Table::column_response()Outputs the response column.
• 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::ajax_insert_auto_draft_post()Ajax handler for adding a new auto-draft post.
• 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_Media_List_Table::_get_row_actions()Gets the row actions for a media item.
• WP_Posts_List_Table::handle_row_actions()Generates and displays row action links.
• WP_REST_Post_Search_Handler::prepare_item()Prepares the search result for a given post ID.
• WP_REST_Posts_Controller::get_item()Retrieves a single post.

Source code

View on Trac ↗View on GitHub ↗

170function get_permalink( $post = 0, $leavename = false ) {171	$rewritecode = array(172		'%year%',173		'%monthnum%',174		'%day%',175		'%hour%',176		'%minute%',177		'%second%',178		$leavename ? '' : '%postname%',179		'%post_id%',180		'%category%',181		'%author%',182		$leavename ? '' : '%pagename%',183	);184 185	if ( is_object( $post ) && isset( $post->filter ) && 'sample' === $post->filter ) {186		$sample = true;187	} else {188		$post   = get_post( $post );189		$sample = false;190	}191 192	if ( empty( $post->ID ) ) {193		return false;194	}195 196	if ( 'page' === $post->post_type ) {197		return get_page_link( $post, $leavename, $sample );198	} elseif ( 'attachment' === $post->post_type ) {199		return get_attachment_link( $post, $leavename );200	} elseif ( in_array( $post->post_type, get_post_types( array( '_builtin' => false ) ), true ) ) {201		return get_post_permalink( $post, $leavename, $sample );202	}203 204	$permalink = get_option( 'permalink_structure' );205 206	/**207	 * Filters the permalink structure for a post before token replacement occurs.208	 *209	 * Only applies to posts with post_type of 'post'.210	 *211	 * @since 3.0.0212	 *213	 * @param string  $permalink The site's permalink structure.214	 * @param WP_Post $post      The post in question.215	 * @param bool    $leavename Whether to keep the post name.216	 */217	$permalink = apply_filters( 'pre_post_link', $permalink, $post, $leavename );218 219	if (220		$permalink &&221		! wp_force_plain_post_permalink( $post )222	) {223 224		$category = '';225		if ( str_contains( $permalink, '%category%' ) ) {226			$cats = get_the_category( $post->ID );227			if ( $cats ) {228				$cats = wp_list_sort(229					$cats,230					array(231						'term_id' => 'ASC',232					)233				);234 235				/**236				 * Filters the category that gets used in the %category% permalink token.237				 *238				 * @since 3.5.0239				 *240				 * @param WP_Term  $cat  The category to use in the permalink.241				 * @param array    $cats Array of all categories (WP_Term objects) associated with the post.242				 * @param WP_Post  $post The post in question.243				 */244				$category_object = apply_filters( 'post_link_category', $cats[0], $cats, $post );245 246				$category_object = get_term( $category_object, 'category' );247				$category        = $category_object->slug;248				if ( $category_object->parent ) {249					$category = get_category_parents( $category_object->parent, false, '/', true ) . $category;

Changelog

Introduced in 1.0.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 7.1.0 tag, from src/wp-includes/link-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.