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