diff --git a/src/wp-includes/default-filters.php b/src/wp-includes/default-filters.php index 1b1f01c571..70da2f2e2a 100644 --- a/src/wp-includes/default-filters.php +++ b/src/wp-includes/default-filters.php @@ -143,6 +143,10 @@ add_filter( 'the_excerpt', 'wpautop' ); add_filter( 'the_excerpt', 'shortcode_unautop'); add_filter( 'get_the_excerpt', 'wp_trim_excerpt' ); +add_filter( 'the_post_thumbnail_caption', 'wptexturize' ); +add_filter( 'the_post_thumbnail_caption', 'convert_smilies' ); +add_filter( 'the_post_thumbnail_caption', 'convert_chars' ); + add_filter( 'comment_text', 'wptexturize' ); add_filter( 'comment_text', 'convert_chars' ); add_filter( 'comment_text', 'make_clickable', 9 ); diff --git a/src/wp-includes/post-thumbnail-template.php b/src/wp-includes/post-thumbnail-template.php index 2b95f4fb70..4722565d96 100644 --- a/src/wp-includes/post-thumbnail-template.php +++ b/src/wp-includes/post-thumbnail-template.php @@ -210,3 +210,44 @@ function the_post_thumbnail_url( $size = 'post-thumbnail' ) { echo esc_url( $url ); } } + +/** + * Returns the post thumbnail caption. + * + * @since 4.6.0 + * + * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`. + * @return string Post thumbnail caption. + */ +function get_the_post_thumbnail_caption( $post = null ) { + $post_thumbnail_id = get_post_thumbnail_id( $post ); + if ( ! $post_thumbnail_id ) { + return ''; + } + + $caption = wp_get_attachment_caption( $post_thumbnail_id ); + + if ( ! $caption ) { + $caption = ''; + } + + return $caption; +} + +/** + * Displays the post thumbnail caption. + * + * @since 4.6.0 + * + * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`. + */ +function the_post_thumbnail_caption( $post = null ) { + /** + * Filters the displayed post thumbnail caption. + * + * @since 4.6.0 + * + * @param string $caption Caption for the given attachment. + */ + echo apply_filters( 'the_post_thumbnail_caption', get_the_post_thumbnail_caption( $post ) ); +} diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php index 61f9018cd7..aa15f7239d 100644 --- a/src/wp-includes/post.php +++ b/src/wp-includes/post.php @@ -4936,6 +4936,37 @@ function wp_get_attachment_url( $post_id = 0 ) { return $url; } +/** + * Retrieves the caption for an attachment. + * + * @since 4.6.0 + * + * @param int $post_id Optional. Attachment ID. Default 0. + * @return string|false False on failure. Attachment caption on success. + */ +function wp_get_attachment_caption( $post_id = 0 ) { + $post_id = (int) $post_id; + if ( ! $post = get_post( $post_id ) ) { + return false; + } + + if ( 'attachment' !== $post->post_type ) { + return false; + } + + $caption = $post->post_excerpt; + + /** + * Filters the attachment caption. + * + * @since 4.6.0 + * + * @param string $caption Caption for the given attachment. + * @param int $post_id Attachment ID. + */ + return apply_filters( 'wp_get_attachment_caption', $caption, $post->ID ); +} + /** * Retrieve thumbnail for an attachment. * diff --git a/tests/phpunit/tests/media.php b/tests/phpunit/tests/media.php index 55311a5766..7bd9f49fcf 100644 --- a/tests/phpunit/tests/media.php +++ b/tests/phpunit/tests/media.php @@ -901,6 +901,40 @@ EOF; $this->assertEquals( $image[0], wp_get_attachment_image_url( $attachment_id ) ); } + /** + * @ticket 12235 + */ + function test_wp_get_attachment_caption() { + $this->assertFalse( wp_get_attachment_caption( 0 ) ); + + $caption = 'This is a caption.'; + + $post_id = self::factory()->post->create(); + $attachment_id = self::factory()->attachment->create_object( $this->img_name, $post_id, array( + 'post_mime_type' => 'image/jpeg', + 'post_type' => 'attachment', + 'post_excerpt' => $caption, + ) ); + + $this->assertFalse( wp_get_attachment_caption( $post_id ) ); + + $this->assertEquals( $caption, wp_get_attachment_caption( $attachment_id ) ); + } + + /** + * @ticket 12235 + */ + function test_wp_get_attachment_caption_empty() { + $post_id = self::factory()->post->create(); + $attachment_id = self::factory()->attachment->create_object( $this->img_name, $post_id, array( + 'post_mime_type' => 'image/jpeg', + 'post_type' => 'attachment', + 'post_excerpt' => '', + ) ); + + $this->assertEquals( '', wp_get_attachment_caption( $attachment_id ) ); + } + /** * Helper function to get image size array from size "name" */ diff --git a/tests/phpunit/tests/post/thumbnails.php b/tests/phpunit/tests/post/thumbnails.php index 822154f1ff..ad232c1149 100644 --- a/tests/phpunit/tests/post/thumbnails.php +++ b/tests/phpunit/tests/post/thumbnails.php @@ -74,6 +74,63 @@ class Tests_Post_Thumbnail_Template extends WP_UnitTestCase { $this->assertTrue( $WP_Query->thumbnails_cached ); } + /** + * @ticket 12235 + */ + function test_get_the_post_thumbnail_caption() { + $this->assertEquals( '', get_the_post_thumbnail_caption() ); + + $caption = 'This is a caption.'; + + $post_id = self::factory()->post->create(); + $attachment_id = self::factory()->attachment->create_object( 'image.jpg', $post_id, array( + 'post_mime_type' => 'image/jpeg', + 'post_type' => 'attachment', + 'post_excerpt' => $caption, + ) ); + + set_post_thumbnail( $post_id, $attachment_id ); + + $this->assertEquals( $caption, get_the_post_thumbnail_caption( $post_id ) ); + } + + /** + * @ticket 12235 + */ + function test_get_the_post_thumbnail_caption_empty() { + $post_id = self::factory()->post->create(); + $attachment_id = self::factory()->attachment->create_object( 'image.jpg', $post_id, array( + 'post_mime_type' => 'image/jpeg', + 'post_type' => 'attachment', + 'post_excerpt' => '', + ) ); + + set_post_thumbnail( $post_id, $attachment_id ); + + $this->assertEquals( '', get_the_post_thumbnail_caption( $post_id ) ); + } + + /** + * @ticket 12235 + */ + function test_the_post_thumbnail_caption() { + $caption = 'This is a caption.'; + + $post_id = self::factory()->post->create(); + $attachment_id = self::factory()->attachment->create_object( 'image.jpg', $post_id, array( + 'post_mime_type' => 'image/jpeg', + 'post_type' => 'attachment', + 'post_excerpt' => $caption, + ) ); + + set_post_thumbnail( $post_id, $attachment_id ); + + ob_start(); + the_post_thumbnail_caption( $post_id ); + + $this->assertEquals( $caption, ob_get_clean() ); + } + function test_get_the_post_thumbnail() { $this->assertEquals( '', get_the_post_thumbnail() ); $this->assertEquals( '', get_the_post_thumbnail( self::$post ) );