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