[ Index ] |
PHP Cross Reference of WordPress |
[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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Sun Feb 28 01:00:03 2021 | Cross-referenced by PHPXref 0.7.1 |