[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   * Retrieve 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      return (int) get_post_meta( $post->ID, '_thumbnail_id', true );
  61  }
  62  
  63  /**
  64   * Display the post thumbnail.
  65   *
  66   * When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size
  67   * is registered, which differs from the 'thumbnail' image size managed via the
  68   * Settings > Media screen.
  69   *
  70   * When using the_post_thumbnail() or related functions, the 'post-thumbnail' image
  71   * size is used by default, though a different size can be specified instead as needed.
  72   *
  73   * @since 2.9.0
  74   *
  75   * @see get_the_post_thumbnail()
  76   *
  77   * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
  78   *                           width and height values in pixels (in that order). Default 'post-thumbnail'.
  79   * @param string|array $attr Optional. Query string or array of attributes. Default empty.
  80   */
  81  function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
  82      echo get_the_post_thumbnail( null, $size, $attr );
  83  }
  84  
  85  /**
  86   * Update cache for thumbnails in the current loop.
  87   *
  88   * @since 3.2.0
  89   *
  90   * @global WP_Query $wp_query WordPress Query object.
  91   *
  92   * @param WP_Query $wp_query Optional. A WP_Query instance. Defaults to the $wp_query global.
  93   */
  94  function update_post_thumbnail_cache( $wp_query = null ) {
  95      if ( ! $wp_query ) {
  96          $wp_query = $GLOBALS['wp_query'];
  97      }
  98  
  99      if ( $wp_query->thumbnails_cached ) {
 100          return;
 101      }
 102  
 103      $thumb_ids = array();
 104  
 105      foreach ( $wp_query->posts as $post ) {
 106          $id = get_post_thumbnail_id( $post->ID );
 107          if ( $id ) {
 108              $thumb_ids[] = $id;
 109          }
 110      }
 111  
 112      if ( ! empty( $thumb_ids ) ) {
 113          _prime_post_caches( $thumb_ids, false, true );
 114      }
 115  
 116      $wp_query->thumbnails_cached = true;
 117  }
 118  
 119  /**
 120   * Retrieve the post thumbnail.
 121   *
 122   * When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size
 123   * is registered, which differs from the 'thumbnail' image size managed via the
 124   * Settings > Media screen.
 125   *
 126   * When using the_post_thumbnail() or related functions, the 'post-thumbnail' image
 127   * size is used by default, though a different size can be specified instead as needed.
 128   *
 129   * @since 2.9.0
 130   * @since 4.4.0 `$post` can be a post ID or WP_Post object.
 131   *
 132   * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
 133   * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array of
 134   *                           width and height values in pixels (in that order). Default 'post-thumbnail'.
 135   * @param string|array $attr Optional. Query string or array of attributes. Default empty.
 136   * @return string The post thumbnail image tag.
 137   */
 138  function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
 139      $post = get_post( $post );
 140  
 141      if ( ! $post ) {
 142          return '';
 143      }
 144  
 145      $post_thumbnail_id = get_post_thumbnail_id( $post );
 146  
 147      /**
 148       * Filters the post thumbnail size.
 149       *
 150       * @since 2.9.0
 151       * @since 4.9.0 Added the `$post_id` parameter.
 152       *
 153       * @param string|int[] $size    Requested image size. Can be any registered image size name, or
 154       *                              an array of width and height values in pixels (in that order).
 155       * @param int          $post_id The post ID.
 156       */
 157      $size = apply_filters( 'post_thumbnail_size', $size, $post->ID );
 158  
 159      if ( $post_thumbnail_id ) {
 160  
 161          /**
 162           * Fires before fetching the post thumbnail HTML.
 163           *
 164           * Provides "just in time" filtering of all filters in wp_get_attachment_image().
 165           *
 166           * @since 2.9.0
 167           *
 168           * @param int          $post_id           The post ID.
 169           * @param int          $post_thumbnail_id The post thumbnail ID.
 170           * @param string|int[] $size              Requested image size. Can be any registered image size name, or
 171           *                                        an array of width and height values in pixels (in that order).
 172           */
 173          do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
 174  
 175          if ( in_the_loop() ) {
 176              update_post_thumbnail_cache();
 177          }
 178  
 179          $html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );
 180  
 181          /**
 182           * Fires after fetching the post thumbnail HTML.
 183           *
 184           * @since 2.9.0
 185           *
 186           * @param int          $post_id           The post ID.
 187           * @param int          $post_thumbnail_id The post thumbnail ID.
 188           * @param string|int[] $size              Requested image size. Can be any registered image size name, or
 189           *                                        an array of width and height values in pixels (in that order).
 190           */
 191          do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
 192  
 193      } else {
 194          $html = '';
 195      }
 196  
 197      /**
 198       * Filters the post thumbnail HTML.
 199       *
 200       * @since 2.9.0
 201       *
 202       * @param string       $html              The post thumbnail HTML.
 203       * @param int          $post_id           The post ID.
 204       * @param int          $post_thumbnail_id The post thumbnail ID.
 205       * @param string|int[] $size              Requested image size. Can be any registered image size name, or
 206       *                                        an array of width and height values in pixels (in that order).
 207       * @param string       $attr              Query string of attributes.
 208       */
 209      return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
 210  }
 211  
 212  /**
 213   * Return the post thumbnail URL.
 214   *
 215   * @since 4.4.0
 216   *
 217   * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
 218   * @param string|int[] $size Optional. Registered image size to retrieve the source for or a flat array
 219   *                           of height and width dimensions. Default 'post-thumbnail'.
 220   * @return string|false Post thumbnail URL or false if no image is available. If `$size` does not match
 221   *                      any registered image size, the original image URL will be returned.
 222   */
 223  function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
 224      $post_thumbnail_id = get_post_thumbnail_id( $post );
 225  
 226      if ( ! $post_thumbnail_id ) {
 227          return false;
 228      }
 229  
 230      return wp_get_attachment_image_url( $post_thumbnail_id, $size );
 231  }
 232  
 233  /**
 234   * Display the post thumbnail URL.
 235   *
 236   * @since 4.4.0
 237   *
 238   * @param string|int[] $size Optional. Image size to use. Accepts any valid image size,
 239   *                           or an array of width and height values in pixels (in that order).
 240   *                           Default 'post-thumbnail'.
 241   */
 242  function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
 243      $url = get_the_post_thumbnail_url( null, $size );
 244  
 245      if ( $url ) {
 246          echo esc_url( $url );
 247      }
 248  }
 249  
 250  /**
 251   * Returns the post thumbnail caption.
 252   *
 253   * @since 4.6.0
 254   *
 255   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 256   * @return string Post thumbnail caption.
 257   */
 258  function get_the_post_thumbnail_caption( $post = null ) {
 259      $post_thumbnail_id = get_post_thumbnail_id( $post );
 260  
 261      if ( ! $post_thumbnail_id ) {
 262          return '';
 263      }
 264  
 265      $caption = wp_get_attachment_caption( $post_thumbnail_id );
 266  
 267      if ( ! $caption ) {
 268          $caption = '';
 269      }
 270  
 271      return $caption;
 272  }
 273  
 274  /**
 275   * Displays the post thumbnail caption.
 276   *
 277   * @since 4.6.0
 278   *
 279   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 280   */
 281  function the_post_thumbnail_caption( $post = null ) {
 282      /**
 283       * Filters the displayed post thumbnail caption.
 284       *
 285       * @since 4.6.0
 286       *
 287       * @param string $caption Caption for the given attachment.
 288       */
 289      echo apply_filters( 'the_post_thumbnail_caption', get_the_post_thumbnail_caption( $post ) );
 290  }