Post Thumbnails: Change the return value of get_post_thumbnail_id() for a non-existing post to false instead of an empty string.

This further makes the function more consistent with `get_the_ID()` or `wp_get_post_parent_id()`, both returning `false` for a non-existing post.

Additionally, document that `get_post_thumbnail_id()` returns `0` if the thumbnail image is not set.

Follow-up to [47160].

Props theMikeD, dingo_d, netpassprodsr, SergeyBiryukov.
Fixes #49832. See #40096.

git-svn-id: https://develop.svn.wordpress.org/trunk@48310 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/post-thumbnail-template.php

@@ -43,15 +43,20 @@ function has_post_thumbnail( $post = null ) {
  *
  * @since 2.9.0
  * @since 4.4.0 `$post` can be a post ID or WP_Post object.
+ * @since 5.5.0 The return value for a non-existing post
+ *              was changed to false instead of an empty string.
  *
  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
- * @return int|string Post thumbnail ID or empty string if the post does not exist.
+ * @return int|false Post thumbnail ID (which can be 0 if the thumbnail is not set),
+ *                   or false if the post does not exist.
  */
 function get_post_thumbnail_id( $post = null ) {
 	$post = get_post( $post );
+
 	if ( ! $post ) {
-		return '';
+		return false;
 	}
+
 	return (int) get_post_meta( $post->ID, '_thumbnail_id', true );
 }
 
@@ -97,6 +102,7 @@ function update_post_thumbnail_cache( $wp_query = null ) {
 	}
 
 	$thumb_ids = array();
+
 	foreach ( $wp_query->posts as $post ) {
 		$id = get_post_thumbnail_id( $post->ID );
 		if ( $id ) {
@@ -133,9 +139,11 @@ function update_post_thumbnail_cache( $wp_query = null ) {
  */
 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 );
 
 	/**
@@ -165,9 +173,11 @@ function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr =
 		 *                                        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 );
 
 		/**
@@ -185,6 +195,7 @@ function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr =
 	} else {
 		$html = '';
 	}
+
 	/**
 	 * Filters the post thumbnail HTML.
 	 *
@@ -212,9 +223,11 @@ function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr =
  */
 function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
 	$post_thumbnail_id = get_post_thumbnail_id( $post );
+
 	if ( ! $post_thumbnail_id ) {
 		return false;
 	}
+
 	return wp_get_attachment_image_url( $post_thumbnail_id, $size );
 }
 
@@ -229,6 +242,7 @@ function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
  */
 function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
 	$url = get_the_post_thumbnail_url( null, $size );
+
 	if ( $url ) {
 		echo esc_url( $url );
 	}
@@ -244,6 +258,7 @@ function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
  */
 function get_the_post_thumbnail_caption( $post = null ) {
 	$post_thumbnail_id = get_post_thumbnail_id( $post );
+
 	if ( ! $post_thumbnail_id ) {
 		return '';
 	}

src/wp-includes/post.php

@@ -7014,7 +7014,8 @@ function _publish_post_hook( $post_id ) {
  * @since 3.1.0
  *
  * @param int|WP_Post $post Post ID or post object. Defaults to global $post.
- * @return int|false Post parent ID (which can be 0 if there is no parent), or false if the post does not exist.
+ * @return int|false Post parent ID (which can be 0 if there is no parent),
+ *                   or false if the post does not exist.
  */
 function wp_get_post_parent_id( $post ) {
 	$post = get_post( $post );

tests/phpunit/tests/post/thumbnails.php

@@ -54,9 +54,9 @@ class Tests_Post_Thumbnail_Template extends WP_UnitTestCase {
 	}
 
 	function test_get_post_thumbnail_id() {
-		$this->assertEmpty( get_post_thumbnail_id( self::$post ) );
+		$this->assertSame( 0, get_post_thumbnail_id( self::$post ) );
-		$this->assertEmpty( get_post_thumbnail_id( self::$post->ID ) );
+		$this->assertSame( 0, get_post_thumbnail_id( self::$post->ID ) );
-		$this->assertEmpty( get_post_thumbnail_id() );
+		$this->assertFalse( get_post_thumbnail_id() );
 
 		set_post_thumbnail( self::$post, self::$attachment_id );