wp_get_attachment_link() WP 2.5.0

Gets a link to the attachment file or WP attachment page. Returns the <a> tag.

• The link will be displayed if the attachment file or page contains:

  1. An image at some specified size, for image attachments; or
  2. A media icon (as specified) representing the attachment; or
  3. The attachment's title (as text) or
  4. Your own text
• If no such attachment exists, the function returns the string Missing Attachment.

Return

String.

• HTML of the link.
• __( 'Missing Attachment' ) if the attachment could not be received.

Usage

wp_get_attachment_link( $id, $size, $permalink, $icon, $text, $attr );

$id(int/WP_Post)

Post ID or post object.
Default: 0

$size(string/array)

Image size. Accepts any valid image size, or an array of width and height values in pixels (in that order).
Default: 'thumbnail'

$permalink(true/false)

Whether to add permalink to image.
Default: false

$icon(true/false)

Whether the attachment is an icon.
Default: false

$text(string/false)

Link text to use. Activated by passing a string, false otherwise.
Default: false

$attr(array/string)

Array or string of attributes.
Default: ''

Examples

#1 Get an attachment of medium size

Default WordPress image sizes: thumbnail, medium, large and full.
The real sizes for them specified on the Settings > Media admin page.

$id = 12144; // Attachment ID
echo wp_get_attachment_link( $id, 'medium' );
/*
result:
<a href='https://example.com/wp-content/uploads/2019/05/image.png'>
	<img width="803" height="803" src="https://example.com/wp-content/uploads/2019/05/image.png" class="attachment-medium size-medium" alt="" />
</a>
*/

#2 Display a link to the WP attachment page

$id = 12144;
echo wp_get_attachment_link( $id, 'thumbnail', true );
/*
result: 
<a href='http://example.com/post_name/'>
	<img width="120" height="120" src="https://example.com/wp-content/uploads/2019/05/image.png" class="attachment-thumbnail size-thumbnail" alt="" />
</a>
*/

#3 Set the custom text for the link

$id = 12144;
echo wp_get_attachment_link( $id, '' , false, false, 'my link text' );
// <a href='https://example.com/wp-content/uploads/2019/05/image.png'>my link text</a>

#4 The link where the text is the post title

$id = 12144;
echo wp_get_attachment_link( $id, '' , false, false, ' ' );
// <a href='https://example.com/wp-content/uploads/2019/05/image.png'>Optimization</a>

#5 WordPress can use icons that represent an attachment

Thumbnails are shown for images, for other files, special pictures are displayed corresponding to the file type (for example, /wp-includes/images/crystal/audio.jpg image for audio file type).

The following example demonstrates how to change the directory where WordPress looks for such icons. For example, we want to use /wp-content/themes/yourtheme/images, then we need to create this directory and add icons there, and then add this code to the functions.php:

add_filter( 'icon_dir', 'my_theme_icon_dyrectory' );
function my_theme_icon_dyrectory($icon_dir) {
	return TEMPLATEPATH . '/images';
}

add_filter( 'icon_dir_uri', 'my_theme_icon_uri' );
function my_theme_icon_uri( $icon_dir ){
	return get_bloginfo('stylesheet_directory') .'/images';
}

Changelog

Code of wp get attachment link: wp-includes/post-template.php ^{WP 5.4.1}

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

	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 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          $id        Post ID.
	 * @param string|array $size      Size of the image. Image size or array of width and height values (in that order).
	 *                                Default 'thumbnail'.
	 * @param bool         $permalink Whether to add permalink to image. Default false.
	 * @param bool         $icon      Whether to include an icon. Default false.
	 * @param string|bool  $text      If string, will be link text. Default false.
	 * @param array|string $attr      Array or string of attributes. Default empty.
	 */
	return apply_filters( 'wp_get_attachment_link', "<a href='" . esc_url( $url ) . "'>$link_text</a>", $id, $size, $permalink, $icon, $text, $attr );
}

Related Functions

From category: Attachments (Media files)

More from Template Tags: Post Thumbnails