[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          $html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );
 190  
 191          /**
 192           * Fires after fetching the post thumbnail HTML.
 193           *
 194           * @since 2.9.0
 195           *
 196           * @param int          $post_id           The post ID.
 197           * @param int          $post_thumbnail_id The post thumbnail ID.
 198           * @param string|int[] $size              Requested image size. Can be any registered image size name, or
 199           *                                        an array of width and height values in pixels (in that order).
 200           */
 201          do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
 202  
 203      } else {
 204          $html = '';
 205      }
 206  
 207      /**
 208       * Filters the post thumbnail HTML.
 209       *
 210       * @since 2.9.0
 211       *
 212       * @param string       $html              The post thumbnail HTML.
 213       * @param int          $post_id           The post ID.
 214       * @param int          $post_thumbnail_id The post thumbnail ID, or 0 if there isn't one.
 215       * @param string|int[] $size              Requested image size. Can be any registered image size name, or
 216       *                                        an array of width and height values in pixels (in that order).
 217       * @param string|array $attr              Query string or array of attributes.
 218       */
 219      return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
 220  }
 221  
 222  /**
 223   * Returns the post thumbnail URL.
 224   *
 225   * @since 4.4.0
 226   *
 227   * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
 228   * @param string|int[] $size Optional. Registered image size to retrieve the source for or a flat array
 229   *                           of height and width dimensions. Default 'post-thumbnail'.
 230   * @return string|false Post thumbnail URL or false if no image is available. If `$size` does not match
 231   *                      any registered image size, the original image URL will be returned.
 232   */
 233  function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
 234      $post_thumbnail_id = get_post_thumbnail_id( $post );
 235  
 236      if ( ! $post_thumbnail_id ) {
 237          return false;
 238      }
 239  
 240      $thumbnail_url = wp_get_attachment_image_url( $post_thumbnail_id, $size );
 241  
 242      /**
 243       * Filters the post thumbnail URL.
 244       *
 245       * @since 5.9.0
 246       *
 247       * @param string|false     $thumbnail_url Post thumbnail URL or false if the post does not exist.
 248       * @param int|WP_Post|null $post          Post ID or WP_Post object. Default is global `$post`.
 249       * @param string|int[]     $size          Registered image size to retrieve the source for or a flat array
 250       *                                        of height and width dimensions. Default 'post-thumbnail'.
 251       */
 252      return apply_filters( 'post_thumbnail_url', $thumbnail_url, $post, $size );
 253  }
 254  
 255  /**
 256   * Displays the post thumbnail URL.
 257   *
 258   * @since 4.4.0
 259   *
 260   * @param string|int[] $size Optional. Image size to use. Accepts any valid image size,
 261   *                           or an array of width and height values in pixels (in that order).
 262   *                           Default 'post-thumbnail'.
 263   */
 264  function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
 265      $url = get_the_post_thumbnail_url( null, $size );
 266  
 267      if ( $url ) {
 268          echo esc_url( $url );
 269      }
 270  }
 271  
 272  /**
 273   * Returns the post thumbnail caption.
 274   *
 275   * @since 4.6.0
 276   *
 277   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 278   * @return string Post thumbnail caption.
 279   */
 280  function get_the_post_thumbnail_caption( $post = null ) {
 281      $post_thumbnail_id = get_post_thumbnail_id( $post );
 282  
 283      if ( ! $post_thumbnail_id ) {
 284          return '';
 285      }
 286  
 287      $caption = wp_get_attachment_caption( $post_thumbnail_id );
 288  
 289      if ( ! $caption ) {
 290          $caption = '';
 291      }
 292  
 293      return $caption;
 294  }
 295  
 296  /**
 297   * Displays the post thumbnail caption.
 298   *
 299   * @since 4.6.0
 300   *
 301   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 302   */
 303  function the_post_thumbnail_caption( $post = null ) {
 304      /**
 305       * Filters the displayed post thumbnail caption.
 306       *
 307       * @since 4.6.0
 308       *
 309       * @param string $caption Caption for the given attachment.
 310       */
 311      echo apply_filters( 'the_post_thumbnail_caption', get_the_post_thumbnail_caption( $post ) );
 312  }