wp_get_attachment_link() – Function | Developer.WordPress.org

Retrieves an attachment page link using an image or icon, if possible.

Parameters

$postint|WP_Postoptional: Post ID or post object.
$sizestring|int[]optional: Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order). Default 'thumbnail'.
Default:'thumbnail'
$permalinkbooloptional: Whether to add permalink to image.
Default:false
$iconbooloptional: Whether the attachment is an icon.
Default:false
$textstring|falseoptional: Link text to use. Activated by passing a string, false otherwise.

Default:false
$attrarray|stringoptional: Array or string of attributes.
Default:''

Return

string HTML content.

Source

function wp_get_attachment_link( $post = 0, $size = 'thumbnail', $permalink = false, $icon = false, $text = false, $attr = '' ) {
	$_post = get_post( $post );

	if ( empty( $_post ) || ( 'attachment' !== $_post->post_type ) || ! wp_get_attachment_url( $_post->ID ) ) {
		return __( 'Missing Attachment' );
	}

	$url = wp_get_attachment_url( $_post->ID );

	if ( $permalink ) {
		$url = get_attachment_link( $_post->ID );
	}

	if ( $text ) {
		$link_text = $text;
	} elseif ( $size && 'none' !== $size ) {
		$link_text = wp_get_attachment_image( $_post->ID, $size, $icon, $attr );
	} else {
		$link_text = '';
	}

	if ( '' === trim( $link_text ) ) {
		$link_text = $_post->post_title;
	}

	if ( '' === trim( $link_text ) ) {
		$link_text = esc_html( pathinfo( get_attached_file( $_post->ID ), PATHINFO_FILENAME ) );
	}

	/**
	 * Filters the list of attachment link attributes.
	 *
	 * @since 6.2.0
	 *
	 * @param array $attributes An array of attributes for the link markup,
	 *                          keyed on the attribute name.
	 * @param int   $id         Post ID.
	 */
	$attributes = apply_filters( 'wp_get_attachment_link_attributes', array( 'href' => $url ), $_post->ID );

	$link_attributes = '';
	foreach ( $attributes as $name => $value ) {
		$value            = 'href' === $name ? esc_url( $value ) : esc_attr( $value );
		$link_attributes .= ' ' . esc_attr( $name ) . "='" . $value . "'";
	}

	$link_html = "<a$link_attributes>$link_text</a>";

	/**
	 * Filters a retrieved attachment page link.
	 *
	 * @since 2.7.0
	 * @since 5.1.0 Added the `$attr` parameter.
	 *
	 * @param string       $link_html The page link HTML output.
	 * @param int|WP_Post  $post      Post ID or object. Can be 0 for the current global post.
	 * @param string|int[] $size      Requested image size. Can be any registered image size name, or
	 *                                an array of width and height values in pixels (in that order).
	 * @param bool         $permalink Whether to add permalink to image. Default false.
	 * @param bool         $icon      Whether to include an icon.
	 * @param string|false $text      If string, will be link text.
	 * @param array|string $attr      Array or string of attributes.
	 */
	return apply_filters( 'wp_get_attachment_link', $link_html, $post, $size, $permalink, $icon, $text, $attr );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_get_attachment_link’, string $link_html, int|WP_Post $post, string|int[] $size, bool $permalink, bool $icon, string|false $text, array|string $attr ): Filters a retrieved attachment page link.
apply_filters( ‘wp_get_attachment_link_attributes’, array $attributes, int $id ): Filters the list of attachment link attributes.

Uses	Description
wp_get_attachment_url()`wp-includes/post.php`	Retrieves the URL for an attachment.
get_attachment_link()`wp-includes/link-template.php`	Retrieves the permalink for an attachment.
get_attached_file()`wp-includes/post.php`	Retrieves attached file path based on attachment ID.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
esc_html()`wp-includes/formatting.php`	Escaping for HTML blocks.
esc_url()`wp-includes/formatting.php`	Checks and cleans a URL.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_post()`wp-includes/post.php`	Retrieves post data given a post ID or post object.

Show 6 more Show less

Used by	Description
prepend_attachment()`wp-includes/post-template.php`	Wraps attachment in paragraph tag before content.
the_attachment_link()`wp-includes/post-template.php`	Displays an attachment page link using an image or icon.

Changelog

Version	Description
4.4.0	The `$post` parameter can now accept either a post ID or `WP_Post` object.
2.5.0	Introduced.

User Contributed Notes

Skip to note 7 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Link Attachment to Post
This example will link the attachment to an attachment page.
```
<?php 
    $id = 9; // ID of an attachment
    echo wp_get_attachment_link( $id, 'thumbnail', true ); 
?>
```
Log in to add feedback
Skip to note 8 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
´Show Medium Size Attachment
The default image sizes of WordPress are “thumbnail”, “medium”, “large” and “full” (the image you uploaded). These image sizes can be configured in the WordPress Administration Media panel under Settings > Media.
```
<?php 
    $id = 9; // ID of an attachment 
    echo wp_get_attachment_link( $id, 'medium' ); 
?>
```
Log in to add feedback
Skip to note 9 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Link Text to Attachment
This example returns an HTML hyperlink with “My link text” linking to an attachment file.
```
<?php 
    $id = 9; // ID of an attachment
    echo wp_get_attachment_link( $id, '' , false, false, 'My link text' ); 
?>
```
Log in to add feedback
Skip to note 10 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Link Post Title to Attachment
This example returns an HTML hyperlink with the post title linking to an attachment file.
```
<?php 
    $id = 9; // ID of an attachment
    echo wp_get_attachment_link( $id, '' ); 
 ?>
```
Log in to add feedback
Skip to note 11 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Change Icon Directory
WordPress can use media icons to represent attachment files on your blog and in the admin interface, if those icons are available. For images it returns the thumbnail. For other media types it looks for image files named by media type (e.g. audio.jpg) in the directory: wp-includes/images/crystal/.

This example shows how you can change this directory to a folder called “images” in your theme: wp-content/themes/yourtheme/images. Create the folder and put the “media type images” in there. To tell WordPress the directory has changed put this in the current theme’s functions.php file:
```
add_filter( 'icon_dir', 'wpdocs_theme_icon_directory' );
add_filter( 'icon_dir_uri', 'wpdocs_theme_icon_uri' );

/**
 * Get the path to the icon directory
 */
function wpdocs_theme_icon_directory( $icon_dir ) {
	return get_stylesheet_directory() . '/images';
}

/**
 * Get the URI of the icon directory
 */
function wpdocs_theme_icon_uri( $icon_dir ) {
	return get_stylesheet_directory_uri() . '/images'; 
}
```
Log in to add feedback
Skip to note 12 content

mrengy 3 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

I was trying to figure out how to link to the “attachment page” rather than the “media file”, and it took me way to long to make sense of the $permalink parameter. I only figured it out by one of the user-contributed examples. Perhaps you could make it more clear by making its name correspond to the terms used in admin when adding an image to a page / post: “link to” – with options of “media file”, “attachment page”, or “custom URL” (entered by the user).

Log in to add feedback

wp_get_attachment_link( int|WP_Post $post, string|int[] $size = ‘thumbnail’, bool $permalink = false, bool $icon = false, string|false $text = false, array|string $attr = ” ): string

In this article

Parameters

Return

Source

Hooks

Changelog

User Contributed Notes

wp_get_attachment_link( int|WP_Post $post, string|int[] $size = ‘thumbnail’, bool $permalink = false, bool $icon = false, string|false $text = false, array|string $attr = ” ): string

In this article

Parameters

Return

Source

Hooks

Related

Changelog

User Contributed Notes