[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * WordPress Post Thumbnail Template Functions.
   4   *
   5   * Support for post thumbnails.
   6   * Theme's functions.php must call add_theme_support( 'post-thumbnails' ) to use these.
   7   *
   8   * @package WordPress
   9   * @subpackage Template
  10   */
  11  
  12  /**
  13   * Determines whether a post has an image attached.
  14   *
  15   * For more information on this and similar theme functions, check out
  16   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
  17   * Conditional Tags} article in the Theme Developer Handbook.
  18   *
  19   * @since 2.9.0
  20   * @since 4.4.0 `$post` can be a post ID or WP_Post object.
  21   *
  22   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
  23   * @return bool Whether the post has an image attached.
  24   */
  25  function has_post_thumbnail( $post = null ) {
  26      $thumbnail_id  = get_post_thumbnail_id( $post );
  27      $has_thumbnail = (bool) $thumbnail_id;
  28  
  29      /**
  30       * Filters whether a post has a post thumbnail.
  31       *
  32       * @since 5.1.0
  33       *
  34       * @param bool             $has_thumbnail true if the post has a post thumbnail, otherwise false.
  35       * @param int|WP_Post|null $post          Post ID or WP_Post object. Default is global `$post`.
  36       * @param int|false        $thumbnail_id  Post thumbnail ID or false if the post does not exist.
  37       */
  38      return (bool) apply_filters( 'has_post_thumbnail', $has_thumbnail, $post, $thumbnail_id );
  39  }
  40  
  41  /**
  42   * Retrieves the post thumbnail ID.
  43   *
  44   * @since 2.9.0
  45   * @since 4.4.0 `$post` can be a post ID or WP_Post object.
  46   * @since 5.5.0 The return value for a non-existing post
  47   *              was changed to false instead of an empty string.
  48   *
  49   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
  50   * @return int|false Post thumbnail ID (which can be 0 if the thumbnail is not set),
  51   *                   or false if the post does not exist.
  52   */
  53  function get_post_thumbnail_id( $post = null ) {
  54      $post = get_post( $post );
  55  
  56      if ( ! $post ) {
  57          return false;
  58      }
  59  
  60      $thumbnail_id = (int) get_post_meta( $post->ID, '_thumbnail_id', true );
  61  
  62      /**
  63       * Filters the post thumbnail ID.
  64       *
  65       * @since 5.9.0
  66       *
  67       * @param int|false        $thumbnail_id Post thumbnail ID or false if the post does not exist.
  68       * @param int|WP_Post|null $post         Post ID or WP_Post object. Default is global `$post`.
  69       */
  70      return (int) apply_filters( 'post_thumbnail_id', $thumbnail_id, $post );
  71  }
  72  
  73  /**
  74   * Displays the post thumbnail.
  75   *
  76   * When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size
  77   * is registered, which differs from the 'thumbnail' image size managed via the
  78   * Settings > Media screen.
  79   *
  80   * When using the_post_thumbnail() or related functions, the 'post-thumbnail' image
  81   * size is used by default, though a different size can be specified instead as needed.
  82   *
  83   * @since 2.9.0
  84   *
  85   * @see get_the_post_thumbnail()
  86   *
  87   * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
  88   *                           width and height values in pixels (in that order). Default 'post-thumbnail'.
  89   * @param string|array $attr Optional. Query string or array of attributes. Default empty.
  90   */
  91  function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
  92      echo get_the_post_thumbnail( null, $size, $attr );
  93  }
  94  
  95  /**
  96   * Updates cache for thumbnails in the current loop.
  97   *
  98   * @since 3.2.0
  99   *
 100   * @global WP_Query $wp_query WordPress Query object.
 101   *
 102   * @param WP_Query $wp_query Optional. A WP_Query instance. Defaults to the $wp_query global.
 103   */
 104  function update_post_thumbnail_cache( $wp_query = null ) {
 105      if ( ! $wp_query ) {
 106          $wp_query = $GLOBALS['wp_query'];
 107      }
 108  
 109      if ( $wp_query->thumbnails_cached ) {
 110          return;
 111      }
 112  
 113      $thumb_ids = array();
 114  
 115      foreach ( $wp_query->posts as $post ) {
 116          $id = get_post_thumbnail_id( $post->ID );
 117          if ( $id ) {
 118              $thumb_ids[] = $id;
 119          }
 120      }
 121  
 122      if ( ! empty( $thumb_ids ) ) {
 123          _prime_post_caches( $thumb_ids, false, true );
 124      }
 125  
 126      $wp_query->thumbnails_cached = true;
 127  }
 128  
 129  /**
 130   * Retrieves the post thumbnail.
 131   *
 132   * When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size
 133   * is registered, which differs from the 'thumbnail' image size managed via the
 134   * Settings > Media screen.
 135   *
 136   * When using the_post_thumbnail() or related functions, the 'post-thumbnail' image
 137   * size is used by default, though a different size can be specified instead as needed.
 138   *
 139   * @since 2.9.0
 140   * @since 4.4.0 `$post` can be a post ID or WP_Post object.
 141   *
 142   * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
 143   * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
 144   *                           width and height values in pixels (in that order). Default 'post-thumbnail'.
 145   * @param string|array $attr Optional. Query string or array of attributes. Default empty.
 146   * @return string The post thumbnail image tag.
 147   */
 148  function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
 149      $post = get_post( $post );
 150  
 151      if ( ! $post ) {
 152          return '';
 153      }
 154  
 155      $post_thumbnail_id = get_post_thumbnail_id( $post );
 156  
 157      /**
 158       * Filters the post thumbnail size.
 159       *
 160       * @since 2.9.0
 161       * @since 4.9.0 Added the `$post_id` parameter.
 162       *
 163       * @param string|int[] $size    Requested image size. Can be any registered image size name, or
 164       *                              an array of width and height values in pixels (in that order).
 165       * @param int          $post_id The post ID.
 166       */
 167      $size = apply_filters( 'post_thumbnail_size', $size, $post->ID );
 168  
 169      if ( $post_thumbnail_id ) {
 170  
 171          /**
 172           * Fires before fetching the post thumbnail HTML.
 173           *
 174           * Provides "just in time" filtering of all filters in wp_get_attachment_image().
 175           *
 176           * @since 2.9.0
 177           *
 178           * @param int          $post_id           The post ID.
 179           * @param int          $post_thumbnail_id The post thumbnail ID.
 180           * @param string|int[] $size              Requested image size. Can be any registered image size name, or
 181           *                                        an array of width and height values in pixels (in that order).
 182           */
 183          do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
 184  
 185          if ( in_the_loop() ) {
 186              update_post_thumbnail_cache();
 187          }
 188  
 189          // Get the 'loading' attribute value to use as default, taking precedence over the default from
 190          // `wp_get_attachment_image()`.
 191          $loading = wp_get_loading_attr_default( 'the_post_thumbnail' );
 192  
 193          // Add the default to the given attributes unless they already include a 'loading' directive.
 194          if ( empty( $attr ) ) {
 195              $attr = array( 'loading' => $loading );
 196          } elseif ( is_array( $attr ) && ! array_key_exists( 'loading', $attr ) ) {
 197              $attr['loading'] = $loading;
 198          } elseif ( is_string( $attr ) && ! preg_match( '/(^|&)loading=/', $attr ) ) {
 199              $attr .= '&loading=' . $loading;
 200          }
 201  
 202          $html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );
 203  
 204          /**
 205           * Fires after fetching the post thumbnail HTML.
 206           *
 207           * @since 2.9.0
 208           *
 209           * @param int          $post_id           The post ID.
 210           * @param int          $post_thumbnail_id The post thumbnail ID.
 211           * @param string|int[] $size              Requested image size. Can be any registered image size name, or
 212           *                                        an array of width and height values in pixels (in that order).
 213           */
 214          do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
 215  
 216      } else {
 217          $html = '';
 218      }
 219  
 220      /**
 221       * Filters the post thumbnail HTML.
 222       *
 223       * @since 2.9.0
 224       *
 225       * @param string       $html              The post thumbnail HTML.
 226       * @param int          $post_id           The post ID.
 227       * @param int          $post_thumbnail_id The post thumbnail ID, or 0 if there isn't one.
 228       * @param string|int[] $size              Requested image size. Can be any registered image size name, or
 229       *                                        an array of width and height values in pixels (in that order).
 230       * @param string|array $attr              Query string or array of attributes.
 231       */
 232      return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
 233  }
 234  
 235  /**
 236   * Returns the post thumbnail URL.
 237   *
 238   * @since 4.4.0
 239   *
 240   * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
 241   * @param string|int[] $size Optional. Registered image size to retrieve the source for or a flat array
 242   *                           of height and width dimensions. Default 'post-thumbnail'.
 243   * @return string|false Post thumbnail URL or false if no image is available. If `$size` does not match
 244   *                      any registered image size, the original image URL will be returned.
 245   */
 246  function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
 247      $post_thumbnail_id = get_post_thumbnail_id( $post );
 248  
 249      if ( ! $post_thumbnail_id ) {
 250          return false;
 251      }
 252  
 253      $thumbnail_url = wp_get_attachment_image_url( $post_thumbnail_id, $size );
 254  
 255      /**
 256       * Filters the post thumbnail URL.
 257       *
 258       * @since 5.9.0
 259       *
 260       * @param string|false     $thumbnail_url Post thumbnail URL or false if the post does not exist.
 261       * @param int|WP_Post|null $post          Post ID or WP_Post object. Default is global `$post`.
 262       * @param string|int[]     $size          Registered image size to retrieve the source for or a flat array
 263       *                                        of height and width dimensions. Default 'post-thumbnail'.
 264       */
 265      return apply_filters( 'post_thumbnail_url', $thumbnail_url, $post, $size );
 266  }
 267  
 268  /**
 269   * Displays the post thumbnail URL.
 270   *
 271   * @since 4.4.0
 272   *
 273   * @param string|int[] $size Optional. Image size to use. Accepts any valid image size,
 274   *                           or an array of width and height values in pixels (in that order).
 275   *                           Default 'post-thumbnail'.
 276   */
 277  function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
 278      $url = get_the_post_thumbnail_url( null, $size );
 279  
 280      if ( $url ) {
 281          echo esc_url( $url );
 282      }
 283  }
 284  
 285  /**
 286   * Returns the post thumbnail caption.
 287   *
 288   * @since 4.6.0
 289   *
 290   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 291   * @return string Post thumbnail caption.
 292   */
 293  function get_the_post_thumbnail_caption( $post = null ) {
 294      $post_thumbnail_id = get_post_thumbnail_id( $post );
 295  
 296      if ( ! $post_thumbnail_id ) {
 297          return '';
 298      }
 299  
 300      $caption = wp_get_attachment_caption( $post_thumbnail_id );
 301  
 302      if ( ! $caption ) {
 303          $caption = '';
 304      }
 305  
 306      return $caption;
 307  }
 308  
 309  /**
 310   * Displays the post thumbnail caption.
 311   *
 312   * @since 4.6.0
 313   *
 314   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 315   */
 316  function the_post_thumbnail_caption( $post = null ) {
 317      /**
 318       * Filters the displayed post thumbnail caption.
 319       *
 320       * @since 4.6.0
 321       *
 322       * @param string $caption Caption for the given attachment.
 323       */
 324      echo apply_filters( 'the_post_thumbnail_caption', get_the_post_thumbnail_caption( $post ) );
 325  }