wp-includes/post-thumbnail-template.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
<?php
/**
 * WordPress Post Thumbnail Template Functions.
 *
 * Support for post thumbnails.
 * Theme's functions.php must call add_theme_support( 'post-thumbnails' ) to use these.
 *
 * @package WordPress
 * @subpackage Template
 */

/**
 * Check if post has an image attached.
 *
 * @since 2.9.0
 * @since 4.4.0 `$post` can be a post ID or WP_Post object.
 *
 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 * @return bool Whether the post has an image attached.
 */
function has_post_thumbnail( $post = null ) {
        return (bool) get_post_thumbnail_id( $post );
}

/**
 * Retrieve post thumbnail ID.
 *
 * @since 2.9.0
 * @since 4.4.0 `$post` can be a post ID or WP_Post object.
 *
 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 * @return string|int Post thumbnail ID or empty string.
 */
function get_post_thumbnail_id( $post = null ) {
        $post = get_post( $post );
        if ( ! $post ) {
                return '';
        }
        return get_post_meta( $post->ID, '_thumbnail_id', true );
}

/**
 * Display the post thumbnail.
 *
 * When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size
 * is registered, which differs from the 'thumbnail' image size managed via the
 * Settings > Media screen.
 *
 * When using the_post_thumbnail() or related functions, the 'post-thumbnail' image
 * size is used by default, though a different size can be specified instead as needed.
 *
 * @since 2.9.0
 *
 * @see get_the_post_thumbnail()
 *
 * @param string|array $size Optional. Image size to use. Accepts any valid image size, or
 *                           an array of width and height values in pixels (in that order).
 *                           Default 'post-thumbnail'.
 * @param string|array $attr Optional. Query string or array of attributes. Default empty.
 */
function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
        echo get_the_post_thumbnail( null, $size, $attr );
}

/**
 * Update cache for thumbnails in the current loop.
 *
 * @since 3.2.0
 *
 * @global WP_Query $wp_query
 *
 * @param WP_Query $wp_query Optional. A WP_Query instance. Defaults to the $wp_query global.
 */
function update_post_thumbnail_cache( $wp_query = null ) {
        if ( ! $wp_query )
                $wp_query = $GLOBALS['wp_query'];

        if ( $wp_query->thumbnails_cached )
                return;

        $thumb_ids = array();
        foreach ( $wp_query->posts as $post ) {
                if ( $id = get_post_thumbnail_id( $post->ID ) )
                        $thumb_ids[] = $id;
        }

        if ( ! empty ( $thumb_ids ) ) {
                _prime_post_caches( $thumb_ids, false, true );
        }

        $wp_query->thumbnails_cached = true;
}

/**
 * Retrieve the post thumbnail.
 *
 * When a theme adds 'post-thumbnail' support, a special 'post-thumbnail' image size
 * is registered, which differs from the 'thumbnail' image size managed via the
 * Settings > Media screen.
 *
 * When using the_post_thumbnail() or related functions, the 'post-thumbnail' image
 * size is used by default, though a different size can be specified instead as needed.
 *
 * @since 2.9.0
 * @since 4.4.0 `$post` can be a post ID or WP_Post object.
 *
 * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
 * @param string|array $size Optional. Image size to use. Accepts any valid image size, or
 *                           an array of width and height values in pixels (in that order).
 *                           Default 'post-thumbnail'.
 * @param string|array $attr Optional. Query string or array of attributes. Default empty.
 * @return string The post thumbnail image tag.
 */
function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
        $post = get_post( $post );
        if ( ! $post ) {
                return '';
        }
        $post_thumbnail_id = get_post_thumbnail_id( $post );

        /**
         * Filters the post thumbnail size.
         *
         * @since 2.9.0
         * @since 4.9.0 Added the `$post_id` parameter.
         *
         * @param string|array $size    The post thumbnail size. Image size or array of width and height
         *                              values (in that order). Default 'post-thumbnail'.
         * @param int          $post_id The post ID.
         */
        $size = apply_filters( 'post_thumbnail_size', $size, $post->ID );

        if ( $post_thumbnail_id ) {

                /**
                 * Fires before fetching the post thumbnail HTML.
                 *
                 * Provides "just in time" filtering of all filters in wp_get_attachment_image().
                 *
                 * @since 2.9.0
                 *
                 * @param int          $post_id           The post ID.
                 * @param string       $post_thumbnail_id The post thumbnail ID.
                 * @param string|array $size              The post thumbnail size. Image size or array of width
                 *                                        and height values (in that order). Default 'post-thumbnail'.
                 */
                do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
                if ( in_the_loop() )
                        update_post_thumbnail_cache();
                $html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );

                /**
                 * Fires after fetching the post thumbnail HTML.
                 *
                 * @since 2.9.0
                 *
                 * @param int          $post_id           The post ID.
                 * @param string       $post_thumbnail_id The post thumbnail ID.
                 * @param string|array $size              The post thumbnail size. Image size or array of width
                 *                                        and height values (in that order). Default 'post-thumbnail'.
                 */
                do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );

        } else {
                $html = '';
        }
        /**
         * Filters the post thumbnail HTML.
         *
         * @since 2.9.0
         *
         * @param string       $html              The post thumbnail HTML.
         * @param int          $post_id           The post ID.
         * @param string       $post_thumbnail_id The post thumbnail ID.
         * @param string|array $size              The post thumbnail size. Image size or array of width and height
         *                                        values (in that order). Default 'post-thumbnail'.
         * @param string       $attr              Query string of attributes.
         */
        return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
}

/**
 * Return the post thumbnail URL.
 *
 * @since 4.4.0
 *
 * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
 * @param string|array $size Optional. Registered image size to retrieve the source for or a flat
 *                           array of height and width dimensions. Default 'post-thumbnail'.
 * @return string|false Post thumbnail URL or false if no URL is available.
 */
function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
        $post_thumbnail_id = get_post_thumbnail_id( $post );
        if ( ! $post_thumbnail_id ) {
                return false;
        }
        return wp_get_attachment_image_url( $post_thumbnail_id, $size );
}

/**
 * Display the post thumbnail URL.
 *
 * @since 4.4.0
 *
 * @param string|array $size Optional. Image size to use. Accepts any valid image size,
 *                           or an array of width and height values in pixels (in that order).
 *                           Default 'post-thumbnail'.
 */
function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
        $url = get_the_post_thumbnail_url( null, $size );
        if ( $url ) {
                echo esc_url( $url );
        }
}

/**
 * Returns the post thumbnail caption.
 *
 * @since 4.6.0
 *
 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 * @return string Post thumbnail caption.
 */
function get_the_post_thumbnail_caption( $post = null ) {
        $post_thumbnail_id = get_post_thumbnail_id( $post );
        if ( ! $post_thumbnail_id ) {
                return '';
        }

        $caption = wp_get_attachment_caption( $post_thumbnail_id );

        if ( ! $caption ) {
                $caption = '';
        }

        return $caption;
}

/**
 * Displays the post thumbnail caption.
 *
 * @since 4.6.0
 *
 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
 */
function the_post_thumbnail_caption( $post = null ) {
        /**
         * Filters the displayed post thumbnail caption.
         *
         * @since 4.6.0
         *
         * @param string $caption Caption for the given attachment.
         */
        echo apply_filters( 'the_post_thumbnail_caption', get_the_post_thumbnail_caption( $post ) );
}