WordPress at a glance

get_the_post_thumbnail() WP 2.9.0

Gets the IMG tag of the post thumbnail (if exists).

Gets the post thumbnail that is specified on the edit post admin page and generates the HTML code of the image <img> based on the received link to the thumbnail. If thumbnail could not be obtained (it is not set), an empty string '' will be returned.

Note! To have ability to set post thumbnails, you need to activate this feature with add_theme_support( 'post-thumbnails' ); in the funstions.php template file.

Use get_the_post_thumbnail_url(), when you need to get the image URL (not image html).

When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size is registered, which differs from the 'thumbnail' image size managed via the Settings > Media screen.

When using the_post_thumbnail() or related functions, the 'post-thumbnail' image size is used by default, though a different size can be specified instead as needed.

Thumbnail styles

Thumbnails created by this function have the wp-post-image class (class="wp-post-image"). Also, the class is set depending on the thumbnail size. In CSS, thumbnails are styled using the following selectors:

img.wp-post-image
img.attachment-thumbnail
img.attachment-medium
img.attachment-large
img.attachment-full

You can specify your class as well:

<?php echo get_the_post_thumbnail( $id, 'thumbnail', [ 'class'=>'alignleft' ] ); ?>
  • Since 4.4.0 $post can be a post ID or WP_Post object.
Is the basis for: the_post_thumbnail()
✈ 1 time = 0.001687s = very slow | 50000 times = 5.72s = fast PHP 7.1.5, WP 4.8.2

No Hooks.

Return

String. The post thumbnail image tag.

Usage

get_the_post_thumbnail( $post, $size, $attr );
$post(int/WP_Post)
Post ID or WP_Post object, thumbnail of which you need to get.
Default: global $post
$size(string/array)

Image size to use.

  • Accepts any valid image size: thumbnail, medium, large, full.
  • Or an array of width and height values in pixels (in that order): array(32, 32).

Default: 'post-thumbnail'

$attr(string/array)

Query string or array of attributes.

$default_attr = array(
	'src'   => $src,
	'class' => "attachment-$size",
	'alt'   => trim( strip_tags( $attachment->post_excerpt ) ),
	'title' => trim( strip_tags( $attachment->post_title ) ),
);

Default: ''

Examples

#1 What the function returns

$thumb = get_the_post_thumbnail( 6462, 'thumbnail' );

/* $thumb =
<img
	width="80" height="80"
	src="/wp-content/uploads/2016/07/http-api-80x80.png"
	class="attachment-thumbnail size-thumbnail wp-post-image"
	alt="WordPress HTTP API"
/>
*/

#2 Basic usage example

<?php $pages = get_pages(array( 'child_of'=>1 )); ?>
<ul>
	<?php foreach( $pages as $page ){ ?>
		<li>
			<?php echo get_the_post_thumbnail( $page->ID, 'thumbnail'); ?>
			<h1><?php echo get_the_title($page); ?></h1>
			<?php echo get_the_excerpt($page); ?>
		</li>
	<?php } ?>
</ul>

#3 Thumbnail sizes

Sizes for images in WordPress are designated conditionally:

  • thumbnail - small thumbnail.
  • medium
  • large
  • full - the original - picture we upload.

You can set your size in pixels for each image-size. Do it on admin page (Settings > Media).

These examples show how you can get a picture of the desired size:

get_the_post_thumbnail( $id ); // without $size parameter

get_the_post_thumbnail( $id, 'thumbnail' ); // small size
get_the_post_thumbnail( $id, 'medium' );    // medium size
get_the_post_thumbnail( $id, 'large' );     // large size

get_the_post_thumbnail( $id, array(100,100) ); // arbitrary size

Code of get_the_post_thumbnail: wp-includes/post-thumbnail-template.php VER 5.0.1

<?php
function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
	$post = get_post( $post );
	if ( ! $post ) {
		return '';
	}
	$post_thumbnail_id = get_post_thumbnail_id( $post );

	/**
	 * Filters the post thumbnail size.
	 *
	 * @since 2.9.0
	 * @since 4.9.0 Added the `$post_id` parameter.
	 *
	 * @param string|array $size    The post thumbnail size. Image size or array of width and height
	 *                              values (in that order). Default 'post-thumbnail'.
	 * @param int          $post_id The post ID.
	 */
	$size = apply_filters( 'post_thumbnail_size', $size, $post->ID );

	if ( $post_thumbnail_id ) {

		/**
		 * Fires before fetching the post thumbnail HTML.
		 *
		 * Provides "just in time" filtering of all filters in wp_get_attachment_image().
		 *
		 * @since 2.9.0
		 *
		 * @param int          $post_id           The post ID.
		 * @param string       $post_thumbnail_id The post thumbnail ID.
		 * @param string|array $size              The post thumbnail size. Image size or array of width
		 *                                        and height values (in that order). Default 'post-thumbnail'.
		 */
		do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
		if ( in_the_loop() )
			update_post_thumbnail_cache();
		$html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );

		/**
		 * Fires after fetching the post thumbnail HTML.
		 *
		 * @since 2.9.0
		 *
		 * @param int          $post_id           The post ID.
		 * @param string       $post_thumbnail_id The post thumbnail ID.
		 * @param string|array $size              The post thumbnail size. Image size or array of width
		 *                                        and height values (in that order). Default 'post-thumbnail'.
		 */
		do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );

	} else {
		$html = '';
	}
	/**
	 * Filters the post thumbnail HTML.
	 *
	 * @since 2.9.0
	 *
	 * @param string       $html              The post thumbnail HTML.
	 * @param int          $post_id           The post ID.
	 * @param string       $post_thumbnail_id The post thumbnail ID.
	 * @param string|array $size              The post thumbnail size. Image size or array of width and height
	 *                                        values (in that order). Default 'post-thumbnail'.
	 * @param string       $attr              Query string of attributes.
	 */
	return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
}

Related Functions

From tag: Thumbnail (images)

More from category: Thumbnails

No comments
    Hello, !     Log In . Register