← Back to branch summary

~canonical-sysadmins/wordpress/4.9.4

« back to all changes in this revision

Viewing changes to wp-includes/class-wp-query.php

  • Committer: Barry Price
  • Date: 2017-11-17 04:49:02 UTC
  • mfrom: (1.1.30 upstream)
  • Revision ID: barry.price@canonical.com-20171117044902-5frux4ycbq6g9fyf
Merge WP4.9 from upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
wp-includes/class-wp-query.php
21
21
         * Query vars set by the user
22
22
         *
23
23
         * @since 1.5.0
24
 
         * @access public
25
24
         * @var array
26
25
         */
27
26
        public $query;
30
29
         * Query vars, after parsing
31
30
         *
32
31
         * @since 1.5.0
33
 
         * @access public
34
32
         * @var array
35
33
         */
36
34
        public $query_vars = array();
39
37
         * Taxonomy query, as passed to get_tax_sql()
40
38
         *
41
39
         * @since 3.1.0
42
 
         * @access public
43
40
         * @var object WP_Tax_Query
44
41
         */
45
42
        public $tax_query;
48
45
         * Metadata query container
49
46
         *
50
47
         * @since 3.2.0
51
 
         * @access public
52
48
         * @var object WP_Meta_Query
53
49
         */
54
50
        public $meta_query = false;
57
53
         * Date query container
58
54
         *
59
55
         * @since 3.7.0
60
 
         * @access public
61
56
         * @var object WP_Date_Query
62
57
         */
63
58
        public $date_query = false;
68
63
         * Holds the contents of a post, page, category, attachment.
69
64
         *
70
65
         * @since 1.5.0
71
 
         * @access public
72
66
         * @var object|array
73
67
         */
74
68
        public $queried_object;
77
71
         * The ID of the queried object.
78
72
         *
79
73
         * @since 1.5.0
80
 
         * @access public
81
74
         * @var int
82
75
         */
83
76
        public $queried_object_id;
86
79
         * Get post database query.
87
80
         *
88
81
         * @since 2.0.1
89
 
         * @access public
90
82
         * @var string
91
83
         */
92
84
        public $request;
95
87
         * List of posts.
96
88
         *
97
89
         * @since 1.5.0
98
 
         * @access public
99
90
         * @var array
100
91
         */
101
92
        public $posts;
104
95
         * The amount of posts for the current query.
105
96
         *
106
97
         * @since 1.5.0
107
 
         * @access public
108
98
         * @var int
109
99
         */
110
100
        public $post_count = 0;
113
103
         * Index of the current item in the loop.
114
104
         *
115
105
         * @since 1.5.0
116
 
         * @access public
117
106
         * @var int
118
107
         */
119
108
        public $current_post = -1;
122
111
         * Whether the loop has started and the caller is in the loop.
123
112
         *
124
113
         * @since 2.0.0
125
 
         * @access public
126
114
         * @var bool
127
115
         */
128
116
        public $in_the_loop = false;
131
119
         * The current post.
132
120
         *
133
121
         * @since 1.5.0
134
 
         * @access public
135
122
         * @var WP_Post
136
123
         */
137
124
        public $post;
140
127
         * The list of comments for current post.
141
128
         *
142
129
         * @since 2.2.0
143
 
         * @access public
144
130
         * @var array
145
131
         */
146
132
        public $comments;
149
135
         * The amount of comments for the posts.
150
136
         *
151
137
         * @since 2.2.0
152
 
         * @access public
153
138
         * @var int
154
139
         */
155
140
        public $comment_count = 0;
158
143
         * The index of the comment in the comment loop.
159
144
         *
160
145
         * @since 2.2.0
161
 
         * @access public
162
146
         * @var int
163
147
         */
164
148
        public $current_comment = -1;
167
151
         * Current comment ID.
168
152
         *
169
153
         * @since 2.2.0
170
 
         * @access public
171
154
         * @var int
172
155
         */
173
156
        public $comment;
178
161
         * If limit clause was not used, equals $post_count.
179
162
         *
180
163
         * @since 2.1.0
181
 
         * @access public
182
164
         * @var int
183
165
         */
184
166
        public $found_posts = 0;
187
169
         * The amount of pages.
188
170
         *
189
171
         * @since 2.1.0
190
 
         * @access public
191
172
         * @var int
192
173
         */
193
174
        public $max_num_pages = 0;
196
177
         * The amount of comment pages.
197
178
         *
198
179
         * @since 2.7.0
199
 
         * @access public
200
180
         * @var int
201
181
         */
202
182
        public $max_num_comment_pages = 0;
203
183
 
204
184
        /**
205
 
         * Set if query is single post.
 
185
         * Signifies whether the current query is for a single post.
206
186
         *
207
187
         * @since 1.5.0
208
 
         * @access public
209
188
         * @var bool
210
189
         */
211
190
        public $is_single = false;
212
191
 
213
192
        /**
214
 
         * Set if query is preview of blog.
 
193
         * Signifies whether the current query is for a preview.
215
194
         *
216
195
         * @since 2.0.0
217
 
         * @access public
218
196
         * @var bool
219
197
         */
220
198
        public $is_preview = false;
221
199
 
222
200
        /**
223
 
         * Set if query returns a page.
 
201
         * Signifies whether the current query is for a page.
224
202
         *
225
203
         * @since 1.5.0
226
 
         * @access public
227
204
         * @var bool
228
205
         */
229
206
        public $is_page = false;
230
207
 
231
208
        /**
232
 
         * Set if query is an archive list.
 
209
         * Signifies whether the current query is for an archive.
233
210
         *
234
211
         * @since 1.5.0
235
 
         * @access public
236
212
         * @var bool
237
213
         */
238
214
        public $is_archive = false;
239
215
 
240
216
        /**
241
 
         * Set if query is part of a date.
 
217
         * Signifies whether the current query is for a date archive.
242
218
         *
243
219
         * @since 1.5.0
244
 
         * @access public
245
220
         * @var bool
246
221
         */
247
222
        public $is_date = false;
248
223
 
249
224
        /**
250
 
         * Set if query contains a year.
 
225
         * Signifies whether the current query is for a year archive.
251
226
         *
252
227
         * @since 1.5.0
253
 
         * @access public
254
228
         * @var bool
255
229
         */
256
230
        public $is_year = false;
257
231
 
258
232
        /**
259
 
         * Set if query contains a month.
 
233
         * Signifies whether the current query is for a month archive.
260
234
         *
261
235
         * @since 1.5.0
262
 
         * @access public
263
236
         * @var bool
264
237
         */
265
238
        public $is_month = false;
266
239
 
267
240
        /**
268
 
         * Set if query contains a day.
 
241
         * Signifies whether the current query is for a day archive.
269
242
         *
270
243
         * @since 1.5.0
271
 
         * @access public
272
244
         * @var bool
273
245
         */
274
246
        public $is_day = false;
275
247
 
276
248
        /**
277
 
         * Set if query contains time.
 
249
         * Signifies whether the current query is for a specific time.
278
250
         *
279
251
         * @since 1.5.0
280
 
         * @access public
281
252
         * @var bool
282
253
         */
283
254
        public $is_time = false;
284
255
 
285
256
        /**
286
 
         * Set if query contains an author.
 
257
         * Signifies whether the current query is for an author archive.
287
258
         *
288
259
         * @since 1.5.0
289
 
         * @access public
290
260
         * @var bool
291
261
         */
292
262
        public $is_author = false;
293
263
 
294
264
        /**
295
 
         * Set if query contains category.
 
265
         * Signifies whether the current query is for a category archive.
296
266
         *
297
267
         * @since 1.5.0
298
 
         * @access public
299
268
         * @var bool
300
269
         */
301
270
        public $is_category = false;
302
271
 
303
272
        /**
304
 
         * Set if query contains tag.
 
273
         * Signifies whether the current query is for a tag archive.
305
274
         *
306
275
         * @since 2.3.0
307
 
         * @access public
308
276
         * @var bool
309
277
         */
310
278
        public $is_tag = false;
311
279
 
312
280
        /**
313
 
         * Set if query contains taxonomy.
 
281
         * Signifies whether the current query is for a taxonomy archive.
314
282
         *
315
283
         * @since 2.5.0
316
 
         * @access public
317
284
         * @var bool
318
285
         */
319
286
        public $is_tax = false;
320
287
 
321
288
        /**
322
 
         * Set if query was part of a search result.
 
289
         * Signifies whether the current query is for a search.
323
290
         *
324
291
         * @since 1.5.0
325
 
         * @access public
326
292
         * @var bool
327
293
         */
328
294
        public $is_search = false;
329
295
 
330
296
        /**
331
 
         * Set if query is feed display.
 
297
         * Signifies whether the current query is for a feed.
332
298
         *
333
299
         * @since 1.5.0
334
 
         * @access public
335
300
         * @var bool
336
301
         */
337
302
        public $is_feed = false;
338
303
 
339
304
        /**
340
 
         * Set if query is comment feed display.
 
305
         * Signifies whether the current query is for a comment feed.
341
306
         *
342
307
         * @since 2.2.0
343
 
         * @access public
344
308
         * @var bool
345
309
         */
346
310
        public $is_comment_feed = false;
347
311
 
348
312
        /**
349
 
         * Set if query is trackback.
 
313
         * Signifies whether the current query is for trackback endpoint call.
350
314
         *
351
315
         * @since 1.5.0
352
 
         * @access public
353
316
         * @var bool
354
317
         */
355
318
        public $is_trackback = false;
356
319
 
357
320
        /**
358
 
         * Set if query is blog homepage.
 
321
         * Signifies whether the current query is for the site homepage.
359
322
         *
360
323
         * @since 1.5.0
361
 
         * @access public
362
324
         * @var bool
363
325
         */
364
326
        public $is_home = false;
365
327
 
366
328
        /**
367
 
         * Set if query couldn't found anything.
 
329
         * Signifies whether the current query couldn't find anything.
368
330
         *
369
331
         * @since 1.5.0
370
 
         * @access public
371
332
         * @var bool
372
333
         */
373
334
        public $is_404 = false;
374
335
 
375
336
        /**
376
 
         * Set if query is embed.
 
337
         * Signifies whether the current query is for an embed.
377
338
         *
378
339
         * @since 4.4.0
379
 
         * @access public
380
340
         * @var bool
381
341
         */
382
342
        public $is_embed = false;
383
343
 
384
344
        /**
385
 
         * Set if query is paged
 
345
         * Signifies whether the current query is for a paged result and not for the first page.
386
346
         *
387
347
         * @since 1.5.0
388
 
         * @access public
389
348
         * @var bool
390
349
         */
391
350
        public $is_paged = false;
392
351
 
393
352
        /**
394
 
         * Set if query is part of administration page.
 
353
         * Signifies whether the current query is for an administrative interface page.
395
354
         *
396
355
         * @since 1.5.0
397
 
         * @access public
398
356
         * @var bool
399
357
         */
400
358
        public $is_admin = false;
401
359
 
402
360
        /**
403
 
         * Set if query is an attachment.
 
361
         * Signifies whether the current query is for an attachment page.
404
362
         *
405
363
         * @since 2.0.0
406
 
         * @access public
407
364
         * @var bool
408
365
         */
409
366
        public $is_attachment = false;
410
367
 
411
368
        /**
412
 
         * Set if is single, is a page, or is an attachment.
 
369
         * Signifies whether the current query is for an existing single post of any post type
 
370
         * (post, attachment, page, custom post types).
413
371
         *
414
372
         * @since 2.1.0
415
 
         * @access public
416
373
         * @var bool
417
374
         */
418
375
        public $is_singular = false;
419
376
 
420
377
        /**
421
 
         * Set if query is for robots.
 
378
         * Signifies whether the current query is for the robots.txt file.
422
379
         *
423
380
         * @since 2.1.0
424
 
         * @access public
425
381
         * @var bool
426
382
         */
427
383
        public $is_robots = false;
428
384
 
429
385
        /**
430
 
         * Set if query contains posts.
 
386
         * Signifies whether the current query is for the page_for_posts page.
431
387
         *
432
388
         * Basically, the homepage if the option isn't set for the static homepage.
433
389
         *
434
390
         * @since 2.1.0
435
 
         * @access public
436
391
         * @var bool
437
392
         */
438
393
        public $is_posts_page = false;
439
394
 
440
395
        /**
441
 
         * Set if query is for a post type archive.
 
396
         * Signifies whether the current query is for a post type archive.
442
397
         *
443
398
         * @since 3.1.0
444
 
         * @access public
445
399
         * @var bool
446
400
         */
447
401
        public $is_post_type_archive = false;
451
405
         * whether we have to re-parse because something has changed
452
406
         *
453
407
         * @since 3.1.0
454
 
         * @access private
455
408
         * @var bool|string
456
409
         */
457
410
        private $query_vars_hash = false;
461
414
         * via pre_get_posts hooks.
462
415
         *
463
416
         * @since 3.1.1
464
 
         * @access private
465
417
         */
466
418
        private $query_vars_changed = true;
467
419
 
469
421
         * Set if post thumbnails are cached
470
422
         *
471
423
         * @since 3.2.0
472
 
         * @access public
473
424
         * @var bool
474
425
         */
475
426
         public $thumbnails_cached = false;
492
443
         * The query flags are what page info WordPress was able to figure out.
493
444
         *
494
445
         * @since 2.0.0
495
 
         * @access private
496
446
         */
497
447
        private function init_query_flags() {
498
448
                $this->is_single = false;
527
477
         * Initiates object properties and sets default values.
528
478
         *
529
479
         * @since 1.5.0
530
 
         * @access public
531
480
         */
532
481
        public function init() {
533
482
                unset($this->posts);
555
504
         * Reparse the query vars.
556
505
         *
557
506
         * @since 1.5.0
558
 
         * @access public
559
507
         */
560
508
        public function parse_query_vars() {
561
509
                $this->parse_query();
566
514
         *
567
515
         * @since 2.1.0
568
516
         * @since 4.4.0 Removed the `comments_popup` public query variable.
569
 
         * @access public
570
517
         *
571
518
         * @param array $array Defined query variables.
572
519
         * @return array Complete query variables with undefined ones filled in empty.
640
587
         *              Introduced the `$comment_status` and `$ping_status` parameters.
641
588
         *              Introduced `RAND(x)` syntax for `$orderby`, which allows an integer seed value to random sorts.
642
589
         * @since 4.6.0 Added 'post_name__in' support for `$orderby`. Introduced the `$lazy_load_term_meta` argument.
643
 
         * @access public
 
590
         * @since 4.9.0 Introduced the `$comment_count` parameter.
644
591
         *
645
592
         * @param string|array $query {
646
593
         *     Optional. Array or string of Query parameters.
656
603
         *     @type array        $category__in            An array of category IDs (OR in, no children).
657
604
         *     @type array        $category__not_in        An array of category IDs (NOT in).
658
605
         *     @type string       $category_name           Use category slug (not name, this or any children).
 
606
         *     @type array|int    $comment_count           Filter results by comment count. Provide an integer to match
 
607
         *                                                 comment count exactly. Provide an array with integer 'value'
 
608
         *                                                 and 'compare' operator ('=', '!=', '>', '>=', '<', '<=' ) to
 
609
         *                                                 compare against comment_count in a specific way.
659
610
         *     @type string       $comment_status          Comment status.
660
611
         *     @type int          $comments_per_page       The number of comments to return per page.
661
612
         *                                                 Default 'comments_per_page' option.
1050
1001
                 *
1051
1002
                 * @since 1.5.0
1052
1003
                 *
1053
 
                 * @param WP_Query &$this The WP_Query instance (passed by reference).
 
1004
                 * @param WP_Query $this The WP_Query instance (passed by reference).
1054
1005
                 */
1055
1006
                do_action_ref_array( 'parse_query', array( &$this ) );
1056
1007
        }
1060
1011
         *
1061
1012
         * For BC, this method is not marked as protected. See [28987].
1062
1013
         *
1063
 
         * @access protected
1064
1014
         * @since 3.1.0
1065
1015
         *
1066
1016
         * @param array $q The query variables. Passed by reference.
1286
1236
        }
1287
1237
 
1288
1238
        /**
1289
 
         * Generate SQL for the WHERE clause based on passed search terms.
 
1239
         * Generates SQL for the WHERE clause based on passed search terms.
1290
1240
         *
1291
1241
         * @since 3.7.0
1292
1242
         *
 
1243
         * @global wpdb $wpdb WordPress database abstraction object.
 
1244
         *
1293
1245
         * @param array $q Query variables.
1294
1246
         * @return string WHERE clause.
1295
1247
         */
1440
1392
        }
1441
1393
 
1442
1394
        /**
1443
 
         * Generate SQL for the ORDER BY condition based on passed search terms.
 
1395
         * Generates SQL for the ORDER BY condition based on passed search terms.
 
1396
         *
 
1397
         * @since 3.7.0
 
1398
         *
 
1399
         * @global wpdb $wpdb WordPress database abstraction object.
1444
1400
         *
1445
1401
         * @param array $q Query variables.
1446
1402
         * @return string ORDER BY clause.
1492
1448
        }
1493
1449
 
1494
1450
        /**
1495
 
         * If the passed orderby value is allowed, convert the alias to a
1496
 
         * properly-prefixed orderby value.
 
1451
         * Converts the given orderby alias (if allowed) to a properly-prefixed value.
1497
1452
         *
1498
1453
         * @since 4.0.0
1499
 
         * @access protected
 
1454
         *
 
1455
         * @global wpdb $wpdb WordPress database abstraction object.
1500
1456
         *
1501
1457
         * @param string $orderby Alias for the field to order by.
1502
1458
         * @return string|false Table-prefixed value to used in the ORDER clause. False otherwise.
1588
1544
         * Parse an 'order' query variable and cast it to ASC or DESC as necessary.
1589
1545
         *
1590
1546
         * @since 4.0.0
1591
 
         * @access protected
1592
1547
         *
1593
1548
         * @param string $order The 'order' query variable.
1594
1549
         * @return string The sanitized 'order' query variable.
1609
1564
         * Sets the 404 property and saves whether query is feed.
1610
1565
         *
1611
1566
         * @since 2.0.0
1612
 
         * @access public
1613
1567
         */
1614
1568
        public function set_404() {
1615
1569
                $is_feed = $this->is_feed;
1626
1580
         * @since 1.5.0
1627
1581
         * @since 3.9.0 The `$default` argument was introduced.
1628
1582
         *
1629
 
         * @access public
1630
1583
         *
1631
1584
         * @param string $query_var Query variable key.
1632
1585
         * @param mixed  $default   Optional. Value to return if the query variable is not set. Default empty.
1644
1597
         * Set query variable.
1645
1598
         *
1646
1599
         * @since 1.5.0
1647
 
         * @access public
1648
1600
         *
1649
1601
         * @param string $query_var Query variable key.
1650
1602
         * @param mixed  $value     Query variable value.
1660
1612
         * database query.
1661
1613
         *
1662
1614
         * @since 1.5.0
1663
 
         * @access public
1664
1615
         *
1665
1616
         * @return array List of posts.
1666
1617
         */
1678
1629
                 *
1679
1630
                 * @since 2.0.0
1680
1631
                 *
1681
 
                 * @param WP_Query &$this The WP_Query instance (passed by reference).
 
1632
                 * @param WP_Query $this The WP_Query instance (passed by reference).
1682
1633
                 */
1683
1634
                do_action_ref_array( 'pre_get_posts', array( &$this ) );
1684
1635
 
2134
2085
                        $whichauthor .= " AND ({$wpdb->posts}.post_author = " . absint($q['author']) . ')';
2135
2086
                }
2136
2087
 
 
2088
                // Matching by comment count.
 
2089
                if ( isset( $q['comment_count'] ) ) {
 
2090
                        // Numeric comment count is converted to array format.
 
2091
                        if ( is_numeric( $q['comment_count'] ) ) {
 
2092
                                $q['comment_count'] = array(
 
2093
                                        'value' => intval( $q['comment_count'] ),
 
2094
                                );
 
2095
                        }
 
2096
 
 
2097
                        if ( isset( $q['comment_count']['value'] ) ) {
 
2098
                                $q['comment_count'] = array_merge( array(
 
2099
                                        'compare' => '=',
 
2100
                                ), $q['comment_count'] );
 
2101
 
 
2102
                                // Fallback for invalid compare operators is '='.
 
2103
                                $compare_operators = array( '=', '!=', '>', '>=', '<', '<=' );
 
2104
                                if ( ! in_array( $q['comment_count']['compare'], $compare_operators, true ) ) {
 
2105
                                        $q['comment_count']['compare'] = '=';
 
2106
                                }
 
2107
 
 
2108
                                $where .= $wpdb->prepare( " AND {$wpdb->posts}.comment_count {$q['comment_count']['compare']} %d", $q['comment_count']['value'] );
 
2109
                        }
 
2110
                }
 
2111
 
2137
2112
                // MIME-Type stuff for attachment browsing
2138
2113
 
2139
2114
                if ( isset( $q['post_mime_type'] ) && '' != $q['post_mime_type'] ) {
2396
2371
                         * @since 1.5.0
2397
2372
                         *
2398
2373
                         * @param string   $where The WHERE clause of the query.
2399
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2374
                         * @param WP_Query $this The WP_Query instance (passed by reference).
2400
2375
                         */
2401
2376
                        $where = apply_filters_ref_array( 'posts_where', array( $where, &$this ) );
2402
2377
 
2405
2380
                         *
2406
2381
                         * @since 1.5.0
2407
2382
                         *
2408
 
                         * @param string   $where The JOIN clause of the query.
2409
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2383
                         * @param string   $join  The JOIN clause of the query.
 
2384
                         * @param WP_Query $this The WP_Query instance (passed by reference).
2410
2385
                         */
2411
2386
                        $join = apply_filters_ref_array( 'posts_join', array( $join, &$this ) );
2412
2387
                }
2446
2421
                                 * @since 2.2.0
2447
2422
                                 *
2448
2423
                                 * @param string   $cjoin The JOIN clause of the query.
2449
 
                                 * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2424
                                 * @param WP_Query $this The WP_Query instance (passed by reference).
2450
2425
                                 */
2451
2426
                                $cjoin = apply_filters_ref_array( 'comment_feed_join', array( $cjoin, &$this ) );
2452
2427
 
2456
2431
                                 * @since 2.2.0
2457
2432
                                 *
2458
2433
                                 * @param string   $cwhere The WHERE clause of the query.
2459
 
                                 * @param WP_Query &$this  The WP_Query instance (passed by reference).
 
2434
                                 * @param WP_Query $this   The WP_Query instance (passed by reference).
2460
2435
                                 */
2461
2436
                                $cwhere = apply_filters_ref_array( 'comment_feed_where', array( $cwhere, &$this ) );
2462
2437
 
2466
2441
                                 * @since 2.2.0
2467
2442
                                 *
2468
2443
                                 * @param string   $cgroupby The GROUP BY clause of the query.
2469
 
                                 * @param WP_Query &$this    The WP_Query instance (passed by reference).
 
2444
                                 * @param WP_Query $this     The WP_Query instance (passed by reference).
2470
2445
                                 */
2471
2446
                                $cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( $cgroupby, &$this ) );
2472
2447
 
2476
2451
                                 * @since 2.8.0
2477
2452
                                 *
2478
2453
                                 * @param string   $corderby The ORDER BY clause of the query.
2479
 
                                 * @param WP_Query &$this    The WP_Query instance (passed by reference).
 
2454
                                 * @param WP_Query $this     The WP_Query instance (passed by reference).
2480
2455
                                 */
2481
2456
                                $corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
2482
2457
 
2486
2461
                                 * @since 2.8.0
2487
2462
                                 *
2488
2463
                                 * @param string   $climits The JOIN clause of the query.
2489
 
                                 * @param WP_Query &$this   The WP_Query instance (passed by reference).
 
2464
                                 * @param WP_Query $this    The WP_Query instance (passed by reference).
2490
2465
                                 */
2491
2466
                                $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
2492
2467
                        }
2527
2502
                         * @since 1.5.0
2528
2503
                         *
2529
2504
                         * @param string   $where The WHERE clause of the query.
2530
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2505
                         * @param WP_Query $this The WP_Query instance (passed by reference).
2531
2506
                         */
2532
2507
                        $where = apply_filters_ref_array( 'posts_where_paged', array( $where, &$this ) );
2533
2508
 
2537
2512
                         * @since 2.0.0
2538
2513
                         *
2539
2514
                         * @param string   $groupby The GROUP BY clause of the query.
2540
 
                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
 
2515
                         * @param WP_Query $this    The WP_Query instance (passed by reference).
2541
2516
                         */
2542
2517
                        $groupby = apply_filters_ref_array( 'posts_groupby', array( $groupby, &$this ) );
2543
2518
 
2549
2524
                         * @since 1.5.0
2550
2525
                         *
2551
2526
                         * @param string   $join  The JOIN clause of the query.
2552
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2527
                         * @param WP_Query $this The WP_Query instance (passed by reference).
2553
2528
                         */
2554
2529
                        $join = apply_filters_ref_array( 'posts_join_paged', array( $join, &$this ) );
2555
2530
 
2559
2534
                         * @since 1.5.1
2560
2535
                         *
2561
2536
                         * @param string   $orderby The ORDER BY clause of the query.
2562
 
                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
 
2537
                         * @param WP_Query $this    The WP_Query instance (passed by reference).
2563
2538
                         */
2564
2539
                        $orderby = apply_filters_ref_array( 'posts_orderby', array( $orderby, &$this ) );
2565
2540
 
2569
2544
                         * @since 2.1.0
2570
2545
                         *
2571
2546
                         * @param string   $distinct The DISTINCT clause of the query.
2572
 
                         * @param WP_Query &$this    The WP_Query instance (passed by reference).
 
2547
                         * @param WP_Query $this     The WP_Query instance (passed by reference).
2573
2548
                         */
2574
2549
                        $distinct = apply_filters_ref_array( 'posts_distinct', array( $distinct, &$this ) );
2575
2550
 
2579
2554
                         * @since 2.1.0
2580
2555
                         *
2581
2556
                         * @param string   $limits The LIMIT clause of the query.
2582
 
                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
 
2557
                         * @param WP_Query $this   The WP_Query instance (passed by reference).
2583
2558
                         */
2584
2559
                        $limits = apply_filters_ref_array( 'post_limits', array( $limits, &$this ) );
2585
2560
 
2589
2564
                         * @since 2.1.0
2590
2565
                         *
2591
2566
                         * @param string   $fields The SELECT clause of the query.
2592
 
                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
 
2567
                         * @param WP_Query $this   The WP_Query instance (passed by reference).
2593
2568
                         */
2594
2569
                        $fields = apply_filters_ref_array( 'posts_fields', array( $fields, &$this ) );
2595
2570
 
2602
2577
                         * @since 3.1.0
2603
2578
                         *
2604
2579
                         * @param array    $clauses The list of clauses for the query.
2605
 
                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
 
2580
                         * @param WP_Query $this    The WP_Query instance (passed by reference).
2606
2581
                         */
2607
2582
                        $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( compact( $pieces ), &$this ) );
2608
2583
 
2639
2614
                         * @since 2.5.0
2640
2615
                         *
2641
2616
                         * @param string   $where The WHERE clause of the query.
2642
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2617
                         * @param WP_Query $this The WP_Query instance (passed by reference).
2643
2618
                         */
2644
2619
                        $where = apply_filters_ref_array( 'posts_where_request', array( $where, &$this ) );
2645
2620
 
2651
2626
                         * @since 2.5.0
2652
2627
                         *
2653
2628
                         * @param string   $groupby The GROUP BY clause of the query.
2654
 
                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
 
2629
                         * @param WP_Query $this    The WP_Query instance (passed by reference).
2655
2630
                         */
2656
2631
                        $groupby = apply_filters_ref_array( 'posts_groupby_request', array( $groupby, &$this ) );
2657
2632
 
2663
2638
                         * @since 2.5.0
2664
2639
                         *
2665
2640
                         * @param string   $join  The JOIN clause of the query.
2666
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2641
                         * @param WP_Query $this The WP_Query instance (passed by reference).
2667
2642
                         */
2668
2643
                        $join = apply_filters_ref_array( 'posts_join_request', array( $join, &$this ) );
2669
2644
 
2675
2650
                         * @since 2.5.0
2676
2651
                         *
2677
2652
                         * @param string   $orderby The ORDER BY clause of the query.
2678
 
                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
 
2653
                         * @param WP_Query $this    The WP_Query instance (passed by reference).
2679
2654
                         */
2680
2655
                        $orderby = apply_filters_ref_array( 'posts_orderby_request', array( $orderby, &$this ) );
2681
2656
 
2687
2662
                         * @since 2.5.0
2688
2663
                         *
2689
2664
                         * @param string   $distinct The DISTINCT clause of the query.
2690
 
                         * @param WP_Query &$this    The WP_Query instance (passed by reference).
 
2665
                         * @param WP_Query $this     The WP_Query instance (passed by reference).
2691
2666
                         */
2692
2667
                        $distinct = apply_filters_ref_array( 'posts_distinct_request', array( $distinct, &$this ) );
2693
2668
 
2699
2674
                         * @since 2.5.0
2700
2675
                         *
2701
2676
                         * @param string   $fields The SELECT clause of the query.
2702
 
                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
 
2677
                         * @param WP_Query $this   The WP_Query instance (passed by reference).
2703
2678
                         */
2704
2679
                        $fields = apply_filters_ref_array( 'posts_fields_request', array( $fields, &$this ) );
2705
2680
 
2711
2686
                         * @since 2.5.0
2712
2687
                         *
2713
2688
                         * @param string   $limits The LIMIT clause of the query.
2714
 
                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
 
2689
                         * @param WP_Query $this   The WP_Query instance (passed by reference).
2715
2690
                         */
2716
2691
                        $limits = apply_filters_ref_array( 'post_limits_request', array( $limits, &$this ) );
2717
2692
 
2726
2701
                         * @since 3.1.0
2727
2702
                         *
2728
2703
                         * @param array    $pieces The pieces of the query.
2729
 
                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
 
2704
                         * @param WP_Query $this   The WP_Query instance (passed by reference).
2730
2705
                         */
2731
2706
                        $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) );
2732
2707
 
2757
2732
                         * @since 2.0.0
2758
2733
                         *
2759
2734
                         * @param string   $request The complete SQL query.
2760
 
                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
 
2735
                         * @param WP_Query $this    The WP_Query instance (passed by reference).
2761
2736
                         */
2762
2737
                        $this->request = apply_filters_ref_array( 'posts_request', array( $this->request, &$this ) );
2763
2738
                }
2776
2751
                 *
2777
2752
                 * @param array|null $posts Return an array of post data to short-circuit WP's query,
2778
2753
                 *                          or null to allow WP to run its normal queries.
2779
 
                 * @param WP_Query   $this  The WP_Query instance, passed by reference.
 
2754
                 * @param WP_Query   $this  The WP_Query instance (passed by reference).
2780
2755
                 */
2781
2756
                $this->posts = apply_filters_ref_array( 'posts_pre_query', array( null, &$this ) );
2782
2757
 
2870
2845
                         * @since 2.3.0
2871
2846
                         *
2872
2847
                         * @param array    $posts The post results array.
2873
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2848
                         * @param WP_Query $this The WP_Query instance (passed by reference).
2874
2849
                         */
2875
2850
                        $this->posts = apply_filters_ref_array( 'posts_results', array( $this->posts, &$this ) );
2876
2851
                }
2942
2917
                                 * @since 2.7.0
2943
2918
                                 *
2944
2919
                                 * @param WP_Post  $post_preview  The Post object.
2945
 
                                 * @param WP_Query &$this         The WP_Query instance (passed by reference).
 
2920
                                 * @param WP_Query $this          The WP_Query instance (passed by reference).
2946
2921
                                 */
2947
2922
                                $this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $this->posts[0], &$this ) ) );
2948
2923
                        }
3002
2977
                         * @since 1.5.0
3003
2978
                         *
3004
2979
                         * @param array    $posts The array of retrieved posts.
3005
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
2980
                         * @param WP_Query $this The WP_Query instance (passed by reference).
3006
2981
                         */
3007
2982
                        $this->posts = apply_filters_ref_array( 'the_posts', array( $this->posts, &$this ) );
3008
2983
                }
3035
3010
         * for the current query.
3036
3011
         *
3037
3012
         * @since 3.5.0
3038
 
         * @access private
3039
3013
         *
3040
3014
         * @param array  $q      Query variables.
3041
3015
         * @param string $limits LIMIT clauses of the query.
3054
3028
                         * @since 2.1.0
3055
3029
                         *
3056
3030
                         * @param string   $found_posts The query to run to find the found posts.
3057
 
                         * @param WP_Query &$this       The WP_Query instance (passed by reference).
 
3031
                         * @param WP_Query $this        The WP_Query instance (passed by reference).
3058
3032
                         */
3059
3033
                        $this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( 'SELECT FOUND_ROWS()', &$this ) ) );
3060
3034
                } else {
3067
3041
                 * @since 2.1.0
3068
3042
                 *
3069
3043
                 * @param int      $found_posts The number of posts found.
3070
 
                 * @param WP_Query &$this       The WP_Query instance (passed by reference).
 
3044
                 * @param WP_Query $this        The WP_Query instance (passed by reference).
3071
3045
                 */
3072
3046
                $this->found_posts = apply_filters_ref_array( 'found_posts', array( $this->found_posts, &$this ) );
3073
3047
 
3079
3053
         * Set up the next post and iterate current post index.
3080
3054
         *
3081
3055
         * @since 1.5.0
3082
 
         * @access public
3083
3056
         *
3084
3057
         * @return WP_Post Next post.
3085
3058
         */
3098
3071
         * property to true.
3099
3072
         *
3100
3073
         * @since 1.5.0
3101
 
         * @access public
3102
3074
         *
3103
3075
         * @global WP_Post $post
3104
3076
         */
3112
3084
                         *
3113
3085
                         * @since 2.0.0
3114
3086
                         *
3115
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
3087
                         * @param WP_Query $this The WP_Query instance (passed by reference).
3116
3088
                         */
3117
3089
                        do_action_ref_array( 'loop_start', array( &$this ) );
3118
3090
 
3126
3098
         * Calls the {@see 'loop_end'} action when the loop is complete.
3127
3099
         *
3128
3100
         * @since 1.5.0
3129
 
         * @access public
3130
3101
         *
3131
3102
         * @return bool True if posts are available, false if end of loop.
3132
3103
         */
3139
3110
                         *
3140
3111
                         * @since 2.0.0
3141
3112
                         *
3142
 
                         * @param WP_Query &$this The WP_Query instance (passed by reference).
 
3113
                         * @param WP_Query $this The WP_Query instance (passed by reference).
3143
3114
                         */
3144
3115
                        do_action_ref_array( 'loop_end', array( &$this ) );
3145
3116
                        // Do some cleaning up after the loop
3146
3117
                        $this->rewind_posts();
 
3118
                } elseif ( 0 === $this->post_count ) {
 
3119
                        /**
 
3120
                         * Fires if no results are found in a post query.
 
3121
                         *
 
3122
                         * @since 4.9.0
 
3123
                         *
 
3124
                         * @param WP_Query $this The WP_Query instance.
 
3125
                         */
 
3126
                        do_action( 'loop_no_results', $this );
3147
3127
                }
3148
3128
 
3149
3129
                $this->in_the_loop = false;
3154
3134
         * Rewind the posts and reset post index.
3155
3135
         *
3156
3136
         * @since 1.5.0
3157
 
         * @access public
3158
3137
         */
3159
3138
        public function rewind_posts() {
3160
3139
                $this->current_post = -1;
3167
3146
         * Iterate current comment index and return WP_Comment object.
3168
3147
         *
3169
3148
         * @since 2.2.0
3170
 
         * @access public
3171
3149
         *
3172
3150
         * @return WP_Comment Comment object.
3173
3151
         */
3182
3160
         * Sets up the current comment.
3183
3161
         *
3184
3162
         * @since 2.2.0
3185
 
         * @access public
3186
3163
         * @global WP_Comment $comment Current comment.
3187
3164
         */
3188
3165
        public function the_comment() {
3206
3183
         * Automatically rewinds comments when finished.
3207
3184
         *
3208
3185
         * @since 2.2.0
3209
 
         * @access public
3210
3186
         *
3211
3187
         * @return bool True, if more comments. False, if no more posts.
3212
3188
         */
3224
3200
         * Rewind the comments, resets the comment index and comment to first.
3225
3201
         *
3226
3202
         * @since 2.2.0
3227
 
         * @access public
3228
3203
         */
3229
3204
        public function rewind_comments() {
3230
3205
                $this->current_comment = -1;
3237
3212
         * Sets up the WordPress query by parsing query string.
3238
3213
         *
3239
3214
         * @since 1.5.0
3240
 
         * @access public
3241
3215
         *
3242
3216
         * @param string|array $query URL query string or array of query arguments.
3243
3217
         * @return array List of posts.
3256
3230
         * query variable. After it is set up, it will be returned.
3257
3231
         *
3258
3232
         * @since 1.5.0
3259
 
         * @access public
3260
3233
         *
3261
3234
         * @return object
3262
3235
         */
3328
3301
         * Retrieve ID of the current queried object.
3329
3302
         *
3330
3303
         * @since 1.5.0
3331
 
         * @access public
3332
3304
         *
3333
3305
         * @return int
3334
3306
         */
3348
3320
         * Sets up the WordPress query, if parameter is not empty.
3349
3321
         *
3350
3322
         * @since 1.5.0
3351
 
         * @access public
3352
3323
         *
3353
3324
         * @param string|array $query URL query string or array of vars.
3354
3325
         */
3362
3333
         * Make private properties readable for backward compatibility.
3363
3334
         *
3364
3335
         * @since 4.0.0
3365
 
         * @access public
3366
3336
         *
3367
3337
         * @param string $name Property to get.
3368
3338
         * @return mixed Property.
3377
3347
         * Make private properties checkable for backward compatibility.
3378
3348
         *
3379
3349
         * @since 4.0.0
3380
 
         * @access public
3381
3350
         *
3382
3351
         * @param string $name Property to check if set.
3383
3352
         * @return bool Whether the property is set.
3392
3361
         * Make private/protected methods readable for backward compatibility.
3393
3362
         *
3394
3363
         * @since 4.0.0
3395
 
         * @access public
3396
3364
         *
3397
3365
         * @param callable $name      Method to call.
3398
3366
         * @param array    $arguments Arguments to pass when calling.
4064
4032
                 * @since 2.8.0
4065
4033
                 * @since 4.1.0 Introduced `$this` parameter.
4066
4034
                 *
4067
 
                 * @param WP_Post  &$post The Post object (passed by reference).
4068
 
                 * @param WP_Query &$this The current Query object (passed by reference).
 
4035
                 * @param WP_Post  $post The Post object (passed by reference).
 
4036
                 * @param WP_Query $this The current Query object (passed by reference).
4069
4037
                 */
4070
4038
                do_action_ref_array( 'the_post', array( &$post, &$this ) );
4071
4039