[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

title

Body

[close]

/wp-includes/ -> post-thumbnail-template.php (source)

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


Generated: Mon Jun 17 08:20:02 2019 Cross-referenced by PHPXref 0.7