[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
 219   *                           array of height and width dimensions. Default 'post-thumbnail'.
 220   * @return string|false Post thumbnail URL or false if no URL is available.
 221   */
 222  function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
 223      $post_thumbnail_id = get_post_thumbnail_id( $post );
 224  
 225      if ( ! $post_thumbnail_id ) {
 226          return false;
 227      }
 228  
 229      return wp_get_attachment_image_url( $post_thumbnail_id, $size );
 230  }
 231  
 232  /**
 233   * Display the post thumbnail URL.
 234   *
 235   * @since 4.4.0
 236   *
 237   * @param string|int[] $size Optional. Image size to use. Accepts any valid image size,
 238   *                           or an array of width and height values in pixels (in that order).
 239   *                           Default 'post-thumbnail'.
 240   */
 241  function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
 242      $url = get_the_post_thumbnail_url( null, $size );
 243  
 244      if ( $url ) {
 245          echo esc_url( $url );
 246      }
 247  }
 248  
 249  /**
 250   * Returns the post thumbnail caption.
 251   *
 252   * @since 4.6.0
 253   *
 254   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 255   * @return string Post thumbnail caption.
 256   */
 257  function get_the_post_thumbnail_caption( $post = null ) {
 258      $post_thumbnail_id = get_post_thumbnail_id( $post );
 259  
 260      if ( ! $post_thumbnail_id ) {
 261          return '';
 262      }
 263  
 264      $caption = wp_get_attachment_caption( $post_thumbnail_id );
 265  
 266      if ( ! $caption ) {
 267          $caption = '';
 268      }
 269  
 270      return $caption;
 271  }
 272  
 273  /**
 274   * Displays the post thumbnail caption.
 275   *
 276   * @since 4.6.0
 277   *
 278   * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 279   */
 280  function the_post_thumbnail_caption( $post = null ) {
 281      /**
 282       * Filters the displayed post thumbnail caption.
 283       *
 284       * @since 4.6.0
 285       *
 286       * @param string $caption Caption for the given attachment.
 287       */
 288      echo apply_filters( 'the_post_thumbnail_caption', get_the_post_thumbnail_caption( $post ) );
 289  }