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