2

I'm having a hard time finding documentation on what the_post_thumbnail() returns if there is no featured image.

If I don't need any additional html around the featured image, should I still use has_post_thumbnail()?

For example, is this redundant:

if ( has_post_thumbnail() ) {
    the_post_thumbnail();
}
6

That kind of detail isn't likely to be in formal documentation, so the best thing to do is just look directly at the source code.

Here it is with the irrelevant parts removed:

function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
    echo get_the_post_thumbnail( null, $size, $attr );
}

/**
 * Retrieve the post thumbnail.
 * @return string The post thumbnail image tag.
 */
function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
    if ( ! $post ) {
        return '';
    }

    $post_thumbnail_id = get_post_thumbnail_id( $post );

    if ( $post_thumbnail_id ) {
        //...
    } else {
        $html = '';
    }

    /**
     * Filters the post thumbnail HTML.
     * @param string       $html              The post thumbnail HTML.
     */
    return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
}

So, you can see that the_post_thumbnail() just echos whatever is returned by get_the_post_thumbnail(). The docblock for get_the_post_thumbnail() declares that it returns a string, and that matches the code.

So, if a featured image isn't set, it should just return an empty string, which will then be echo'd, which will have no effect on the rendered markup.

If another plugin filters the output of post_thumbnail_html, then it could return something else, of course, even if a thumbnail isn't set.

So, in your specific case, wrapping the call in has_post_thumbnail() would just be a precaution against unintended side-effects, but it doesn't seem likely that you'll run into any problems if you leave it out.

In you wanted to add extra markup around the image, though, then it would be necessary (props @swisspidy). e.g.:

<?php if ( has_post_thumbnail() ) : ?>
    <header class="entry-header">
        <?php the_post_thumbnail(); ?>
        <p>Lorum ipsum blah blah blah</p>
    </header>
<?php endif; ?>
  • 2
    The conditional check is mostly useful when you want to wrap the featured image in some custom markup :) – swissspidy Feb 1 '18 at 21:14
  • That's a great point Pascal, I've incorporated that into the answer :) – Ian Dunn Feb 1 '18 at 21:28
  • 1
    Actually, if you look at the source, the final return is passed through the post_thumbnail_html filter, so it is possible that a plugin or theme might hook into that to add additional HTML. Because of that, I'd say it's probably worthwhile continuing to use has_post_thumbnail() just in case the plugin or theme is badly written! – Peter HvD Feb 2 '18 at 16:57
  • Yeah, that's what I was referring to with If another plugin filters the output, then it could return something else, of course, even if a thumbnail isn't set. I'll update it to explicitly name the filter, to avoid confusion. – Ian Dunn Feb 2 '18 at 19:22

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.