WordPress 4.5-scripts

[autoinstalls/wordpress.git] / wp-includes / post-thumbnail-template.php

diff --git a/wp-includes/post-thumbnail-template.php b/wp-includes/post-thumbnail-template.php
index f1d70364576e9873cec59003f3eeeead8f31cacb..2862bdc93cc02df5f6139946491eb563daa370d4 100644 (file)
--- a/wp-includes/post-thumbnail-template.php
+++ b/wp-includes/post-thumbnail-template.php
@@ -13,25 +13,30 @@
  * Check if post has an image attached.
  *
  * @since 2.9.0
+ * @since 4.4.0 `$post` can be a post ID or WP_Post object.
  *
- * @param int $post_id Optional. Post ID.
- * @return bool Whether post has an image attached.
+ * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
+ * @return bool Whether the post has an image attached.
  */
-function has_post_thumbnail( $post_id = null ) {
-       return (bool) get_post_thumbnail_id( $post_id );
+function has_post_thumbnail( $post = null ) {
+       return (bool) get_post_thumbnail_id( $post );
 }
 
 /**
- * Retrieve Post Thumbnail ID.
+ * Retrieve post thumbnail ID.
  *
  * @since 2.9.0
+ * @since 4.4.0 `$post` can be a post ID or WP_Post object.
  *
- * @param int $post_id Optional. Post ID.
- * @return int
+ * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
+ * @return string|int Post thumbnail ID or empty string.
  */
-function get_post_thumbnail_id( $post_id = null ) {
-       $post_id = ( null === $post_id ) ? get_the_ID() : $post_id;
-       return get_post_meta( $post_id, '_thumbnail_id', true );
+function get_post_thumbnail_id( $post = null ) {
+       $post = get_post( $post );
+       if ( ! $post ) {
+               return '';
+       }
+       return get_post_meta( $post->ID, '_thumbnail_id', true );
 }
 
 /**
@@ -48,8 +53,9 @@ function get_post_thumbnail_id( $post_id = null ) {
  *
  * @see get_the_post_thumbnail()
  *
- * @param string|array $size Optional. Registered image size to use, or flat array of height
- *                           and width values. Default 'post-thumbnail'.
+ * @param string|array $size Optional. Image size to use. Accepts any valid image size, or
+ *                           an array of width and height values in pixels (in that order).
+ *                           Default 'post-thumbnail'.
  * @param string|array $attr Optional. Query string or array of attributes. Default empty.
  */
 function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
@@ -57,11 +63,13 @@ function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
 }
 
 /**
- * Update cache for thumbnails in the current loop
+ * Update cache for thumbnails in the current loop.
  *
  * @since 3.2.0
  *
- * @param object $wp_query Optional. A WP_Query instance. Defaults to the $wp_query global.
+ * @global WP_Query $wp_query
+ *
+ * @param WP_Query $wp_query Optional. A WP_Query instance. Defaults to the $wp_query global.
  */
 function update_post_thumbnail_cache( $wp_query = null ) {
        if ( ! $wp_query )
@@ -94,22 +102,29 @@ function update_post_thumbnail_cache( $wp_query = null ) {
  * size is used by default, though a different size can be specified instead as needed.
  *
  * @since 2.9.0
+ * @since 4.4.0 `$post` can be a post ID or WP_Post object.
  *
- * @param int $post_id       Post ID. Default is the ID of the `$post` global.
- * @param string|array $size Optional. Registered image size to use, or flat array of height
- *                           and width values. Default 'post-thumbnail'.
+ * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
+ * @param string|array $size Optional. Image size to use. Accepts any valid image size, or
+ *                           an array of width and height values in pixels (in that order).
+ *                           Default 'post-thumbnail'.
  * @param string|array $attr Optional. Query string or array of attributes. Default empty.
+ * @return string The post thumbnail image tag.
  */
-function get_the_post_thumbnail( $post_id = null, $size = 'post-thumbnail', $attr = '' ) {
-       $post_id = ( null === $post_id ) ? get_the_ID() : $post_id;
-       $post_thumbnail_id = get_post_thumbnail_id( $post_id );
+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 );
 
        /**
         * Filter the post thumbnail size.
         *
         * @since 2.9.0
         *
-        * @param string $size The post thumbnail size.
+        * @param string|array $size The post thumbnail size. Image size or array of width and height
+        *                           values (in that order). Default 'post-thumbnail'.
         */
        $size = apply_filters( 'post_thumbnail_size', $size );
 
@@ -122,11 +137,12 @@ function get_the_post_thumbnail( $post_id = null, $size = 'post-thumbnail', $att
                 *
                 * @since 2.9.0
                 *
-                * @param string $post_id           The post ID.
-                * @param string $post_thumbnail_id The post thumbnail ID.
-                * @param string $size              The post thumbnail size.
+                * @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 );
+               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 );
@@ -136,11 +152,12 @@ function get_the_post_thumbnail( $post_id = null, $size = 'post-thumbnail', $att
                 *
                 * @since 2.9.0
                 *
-                * @param string $post_id           The post ID.
-                * @param string $post_thumbnail_id The post thumbnail ID.
-                * @param string $size              The post thumbnail size.
+                * @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 );
+               do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
 
        } else {
                $html = '';
@@ -150,11 +167,46 @@ function get_the_post_thumbnail( $post_id = null, $size = 'post-thumbnail', $att
         *
         * @since 2.9.0
         *
-        * @param string $html              The post thumbnail HTML.
-        * @param string $post_id           The post ID.
-        * @param string $post_thumbnail_id The post thumbnail ID.
-        * @param string $size              The post thumbnail size.
-        * @param string $attr              Query string of attributes.
+        * @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 );
+       return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
+}
+
+/**
+ * Return the post thumbnail URL.
+ *
+ * @since 4.4.0
+ *
+ * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
+ * @param string|array $size Optional. Registered image size to retrieve the source for or a flat
+ *                           array of height and width dimensions. Default 'post-thumbnail'.
+ * @return string|false Post thumbnail URL or false if no URL is available.
+ */
+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 );
+}
+
+/**
+ * Display the post thumbnail URL.
+ *
+ * @since 4.4.0
+ *
+ * @param string|array $size Optional. Image size to use. Accepts any valid image size,
+ *                           or an array of width and height values in pixels (in that order).
+ *                           Default 'post-thumbnail'.
+ */
+function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
+       $url = get_the_post_thumbnail_url( null, $size );
+       if ( $url ) {
+               echo esc_url( $url );
+       }
 }