5 * The query API attempts to get which part of WordPress the user is on. It
6 * also provides functionality for getting URL query information.
8 * @link https://codex.wordpress.org/The_Loop More information on The Loop.
15 * Retrieve variable in the WP_Query class.
18 * @since 3.9.0 The `$default` argument was introduced.
20 * @global WP_Query $wp_query Global WP_Query instance.
22 * @param string $var The variable key to retrieve.
23 * @param mixed $default Optional. Value to return if the query variable is not set. Default empty.
24 * @return mixed Contents of the query variable.
26 function get_query_var( $var, $default = '' ) {
28 return $wp_query->get( $var, $default );
32 * Retrieve the currently-queried object.
34 * Wrapper for WP_Query::get_queried_object().
39 * @global WP_Query $wp_query Global WP_Query instance.
41 * @return object Queried object.
43 function get_queried_object() {
45 return $wp_query->get_queried_object();
49 * Retrieve ID of the current queried object.
51 * Wrapper for WP_Query::get_queried_object_id().
55 * @global WP_Query $wp_query Global WP_Query instance.
57 * @return int ID of the queried object.
59 function get_queried_object_id() {
61 return $wp_query->get_queried_object_id();
69 * @global WP_Query $wp_query Global WP_Query instance.
71 * @param string $var Query variable key.
72 * @param mixed $value Query variable value.
74 function set_query_var( $var, $value ) {
76 $wp_query->set( $var, $value );
80 * Sets up The Loop with query parameters.
82 * Note: This function will completely override the main query and isn't intended for use
83 * by plugins or themes. Its overly-simplistic approach to modifying the main query can be
84 * problematic and should be avoided wherever possible. In most cases, there are better,
85 * more performant options for modifying the main query such as via the {@see 'pre_get_posts'}
86 * action within WP_Query.
88 * This must not be used within the WordPress Loop.
92 * @global WP_Query $wp_query Global WP_Query instance.
94 * @param array|string $query Array or string of WP_Query arguments.
95 * @return array List of post objects.
97 function query_posts($query) {
98 $GLOBALS['wp_query'] = new WP_Query();
99 return $GLOBALS['wp_query']->query($query);
103 * Destroys the previous query and sets up a new query.
105 * This should be used after query_posts() and before another query_posts().
106 * This will remove obscure bugs that occur when the previous WP_Query object
107 * is not destroyed properly before another is set up.
111 * @global WP_Query $wp_query Global WP_Query instance.
112 * @global WP_Query $wp_the_query Copy of the global WP_Query instance created during wp_reset_query().
114 function wp_reset_query() {
115 $GLOBALS['wp_query'] = $GLOBALS['wp_the_query'];
120 * After looping through a separate query, this function restores
121 * the $post global to the current post in the main query.
125 * @global WP_Query $wp_query Global WP_Query instance.
127 function wp_reset_postdata() {
130 if ( isset( $wp_query ) ) {
131 $wp_query->reset_postdata();
140 * Is the query for an existing archive page?
142 * Month, Year, Category, Author, Post Type archive...
146 * @global WP_Query $wp_query Global WP_Query instance.
150 function is_archive() {
153 if ( ! isset( $wp_query ) ) {
154 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
158 return $wp_query->is_archive();
162 * Is the query for an existing post type archive page?
166 * @global WP_Query $wp_query Global WP_Query instance.
168 * @param string|array $post_types Optional. Post type or array of posts types to check against.
171 function is_post_type_archive( $post_types = '' ) {
174 if ( ! isset( $wp_query ) ) {
175 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
179 return $wp_query->is_post_type_archive( $post_types );
183 * Is the query for an existing attachment page?
187 * @global WP_Query $wp_query Global WP_Query instance.
189 * @param int|string|array|object $attachment Attachment ID, title, slug, or array of such.
192 function is_attachment( $attachment = '' ) {
195 if ( ! isset( $wp_query ) ) {
196 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
200 return $wp_query->is_attachment( $attachment );
204 * Is the query for an existing author archive page?
206 * If the $author parameter is specified, this function will additionally
207 * check if the query is for one of the authors specified.
211 * @global WP_Query $wp_query Global WP_Query instance.
213 * @param mixed $author Optional. User ID, nickname, nicename, or array of User IDs, nicknames, and nicenames
216 function is_author( $author = '' ) {
219 if ( ! isset( $wp_query ) ) {
220 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
224 return $wp_query->is_author( $author );
228 * Is the query for an existing category archive page?
230 * If the $category parameter is specified, this function will additionally
231 * check if the query is for one of the categories specified.
235 * @global WP_Query $wp_query Global WP_Query instance.
237 * @param mixed $category Optional. Category ID, name, slug, or array of Category IDs, names, and slugs.
240 function is_category( $category = '' ) {
243 if ( ! isset( $wp_query ) ) {
244 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
248 return $wp_query->is_category( $category );
252 * Is the query for an existing tag archive page?
254 * If the $tag parameter is specified, this function will additionally
255 * check if the query is for one of the tags specified.
259 * @global WP_Query $wp_query Global WP_Query instance.
261 * @param mixed $tag Optional. Tag ID, name, slug, or array of Tag IDs, names, and slugs.
264 function is_tag( $tag = '' ) {
267 if ( ! isset( $wp_query ) ) {
268 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
272 return $wp_query->is_tag( $tag );
276 * Is the query for an existing custom taxonomy archive page?
278 * If the $taxonomy parameter is specified, this function will additionally
279 * check if the query is for that specific $taxonomy.
281 * If the $term parameter is specified in addition to the $taxonomy parameter,
282 * this function will additionally check if the query is for one of the terms
287 * @global WP_Query $wp_query Global WP_Query instance.
289 * @param string|array $taxonomy Optional. Taxonomy slug or slugs.
290 * @param int|string|array $term Optional. Term ID, name, slug or array of Term IDs, names, and slugs.
291 * @return bool True for custom taxonomy archive pages, false for built-in taxonomies (category and tag archives).
293 function is_tax( $taxonomy = '', $term = '' ) {
296 if ( ! isset( $wp_query ) ) {
297 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
301 return $wp_query->is_tax( $taxonomy, $term );
305 * Is the query for an existing date archive?
309 * @global WP_Query $wp_query Global WP_Query instance.
316 if ( ! isset( $wp_query ) ) {
317 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
321 return $wp_query->is_date();
325 * Is the query for an existing day archive?
329 * @global WP_Query $wp_query Global WP_Query instance.
336 if ( ! isset( $wp_query ) ) {
337 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
341 return $wp_query->is_day();
345 * Is the query for a feed?
349 * @global WP_Query $wp_query Global WP_Query instance.
351 * @param string|array $feeds Optional feed types to check.
354 function is_feed( $feeds = '' ) {
357 if ( ! isset( $wp_query ) ) {
358 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
362 return $wp_query->is_feed( $feeds );
366 * Is the query for a comments feed?
370 * @global WP_Query $wp_query Global WP_Query instance.
374 function is_comment_feed() {
377 if ( ! isset( $wp_query ) ) {
378 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
382 return $wp_query->is_comment_feed();
386 * Is the query for the front page of the site?
388 * This is for what is displayed at your site's main URL.
390 * Depends on the site's "Front page displays" Reading Settings 'show_on_front' and 'page_on_front'.
392 * If you set a static page for the front page of your site, this function will return
393 * true when viewing that page.
395 * Otherwise the same as @see is_home()
399 * @global WP_Query $wp_query Global WP_Query instance.
401 * @return bool True, if front of site.
403 function is_front_page() {
406 if ( ! isset( $wp_query ) ) {
407 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
411 return $wp_query->is_front_page();
415 * Determines if the query is for the blog homepage.
417 * The blog homepage is the page that shows the time-based blog content of the site.
419 * is_home() is dependent on the site's "Front page displays" Reading Settings 'show_on_front'
420 * and 'page_for_posts'.
422 * If a static page is set for the front page of the site, this function will return true only
423 * on the page you set as the "Posts page".
427 * @see is_front_page()
428 * @global WP_Query $wp_query Global WP_Query instance.
430 * @return bool True if blog view homepage, otherwise false.
435 if ( ! isset( $wp_query ) ) {
436 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
440 return $wp_query->is_home();
444 * Is the query for an existing month archive?
448 * @global WP_Query $wp_query Global WP_Query instance.
452 function is_month() {
455 if ( ! isset( $wp_query ) ) {
456 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
460 return $wp_query->is_month();
464 * Is the query for an existing single page?
466 * If the $page parameter is specified, this function will additionally
467 * check if the query is for one of the pages specified.
474 * @global WP_Query $wp_query Global WP_Query instance.
476 * @param int|string|array $page Optional. Page ID, title, slug, or array of such. Default empty.
477 * @return bool Whether the query is for an existing single page.
479 function is_page( $page = '' ) {
482 if ( ! isset( $wp_query ) ) {
483 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
487 return $wp_query->is_page( $page );
491 * Is the query for paged result and not for the first page?
495 * @global WP_Query $wp_query Global WP_Query instance.
499 function is_paged() {
502 if ( ! isset( $wp_query ) ) {
503 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
507 return $wp_query->is_paged();
511 * Is the query for a post or page preview?
515 * @global WP_Query $wp_query Global WP_Query instance.
519 function is_preview() {
522 if ( ! isset( $wp_query ) ) {
523 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
527 return $wp_query->is_preview();
531 * Is the query for the robots file?
535 * @global WP_Query $wp_query Global WP_Query instance.
539 function is_robots() {
542 if ( ! isset( $wp_query ) ) {
543 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
547 return $wp_query->is_robots();
551 * Is the query for a search?
555 * @global WP_Query $wp_query Global WP_Query instance.
559 function is_search() {
562 if ( ! isset( $wp_query ) ) {
563 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
567 return $wp_query->is_search();
571 * Is the query for an existing single post?
573 * Works for any post type, except attachments and pages
575 * If the $post parameter is specified, this function will additionally
576 * check if the query is for one of the Posts specified.
583 * @global WP_Query $wp_query Global WP_Query instance.
585 * @param int|string|array $post Optional. Post ID, title, slug, or array of such. Default empty.
586 * @return bool Whether the query is for an existing single post.
588 function is_single( $post = '' ) {
591 if ( ! isset( $wp_query ) ) {
592 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
596 return $wp_query->is_single( $post );
600 * Is the query for an existing single post of any post type (post, attachment, page, ... )?
602 * If the $post_types parameter is specified, this function will additionally
603 * check if the query is for one of the Posts Types specified.
610 * @global WP_Query $wp_query Global WP_Query instance.
612 * @param string|array $post_types Optional. Post type or array of post types. Default empty.
613 * @return bool Whether the query is for an existing single post of any of the given post types.
615 function is_singular( $post_types = '' ) {
618 if ( ! isset( $wp_query ) ) {
619 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
623 return $wp_query->is_singular( $post_types );
627 * Is the query for a specific time?
631 * @global WP_Query $wp_query Global WP_Query instance.
638 if ( ! isset( $wp_query ) ) {
639 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
643 return $wp_query->is_time();
647 * Is the query for a trackback endpoint call?
651 * @global WP_Query $wp_query Global WP_Query instance.
655 function is_trackback() {
658 if ( ! isset( $wp_query ) ) {
659 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
663 return $wp_query->is_trackback();
667 * Is the query for an existing year archive?
671 * @global WP_Query $wp_query Global WP_Query instance.
678 if ( ! isset( $wp_query ) ) {
679 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
683 return $wp_query->is_year();
687 * Is the query a 404 (returns no results)?
691 * @global WP_Query $wp_query Global WP_Query instance.
698 if ( ! isset( $wp_query ) ) {
699 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
703 return $wp_query->is_404();
707 * Is the query for an embedded post?
711 * @global WP_Query $wp_query Global WP_Query instance.
713 * @return bool Whether we're in an embedded post or not.
715 function is_embed() {
718 if ( ! isset( $wp_query ) ) {
719 _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
723 return $wp_query->is_embed();
727 * Is the query the main query?
731 * @global WP_Query $wp_query Global WP_Query instance.
735 function is_main_query() {
736 if ( 'pre_get_posts' === current_filter() ) {
738 /* translators: 1: pre_get_posts 2: WP_Query->is_main_query() 3: is_main_query() 4: link to codex is_main_query() page. */
739 __( 'In %1$s, use the %2$s method, not the %3$s function. See %4$s.' ),
740 '<code>pre_get_posts</code>',
741 '<code>WP_Query->is_main_query()</code>',
742 '<code>is_main_query()</code>',
743 __( 'https://codex.wordpress.org/Function_Reference/is_main_query' )
745 _doing_it_wrong( __FUNCTION__, $message, '3.7.0' );
749 return $wp_query->is_main_query();
753 * The Loop. Post loop control.
757 * Whether current WordPress query has results to loop over.
761 * @global WP_Query $wp_query Global WP_Query instance.
765 function have_posts() {
767 return $wp_query->have_posts();
771 * Whether the caller is in the Loop.
775 * @global WP_Query $wp_query Global WP_Query instance.
777 * @return bool True if caller is within loop, false if loop hasn't started or ended.
779 function in_the_loop() {
781 return $wp_query->in_the_loop;
785 * Rewind the loop posts.
789 * @global WP_Query $wp_query Global WP_Query instance.
791 function rewind_posts() {
793 $wp_query->rewind_posts();
797 * Iterate the post index in the loop.
801 * @global WP_Query $wp_query Global WP_Query instance.
803 function the_post() {
805 $wp_query->the_post();
813 * Whether there are comments to loop over.
817 * @global WP_Query $wp_query Global WP_Query instance.
821 function have_comments() {
823 return $wp_query->have_comments();
827 * Iterate comment index in the comment loop.
831 * @global WP_Query $wp_query Global WP_Query instance.
835 function the_comment() {
837 return $wp_query->the_comment();
841 * Redirect old slugs to the correct permalink.
843 * Attempts to find the current slug from the past slugs.
847 * @global wpdb $wpdb WordPress database abstraction object.
849 function wp_old_slug_redirect() {
850 if ( is_404() && '' !== get_query_var( 'name' ) ) {
853 // Guess the current post_type based on the query vars.
854 if ( get_query_var( 'post_type' ) ) {
855 $post_type = get_query_var( 'post_type' );
856 } elseif ( get_query_var( 'attachment' ) ) {
857 $post_type = 'attachment';
858 } elseif ( get_query_var( 'pagename' ) ) {
864 if ( is_array( $post_type ) ) {
865 if ( count( $post_type ) > 1 ) {
868 $post_type = reset( $post_type );
871 // Do not attempt redirect for hierarchical post types
872 if ( is_post_type_hierarchical( $post_type ) ) {
876 $query = $wpdb->prepare("SELECT post_id FROM $wpdb->postmeta, $wpdb->posts WHERE ID = post_id AND post_type = %s AND meta_key = '_wp_old_slug' AND meta_value = %s", $post_type, get_query_var( 'name' ) );
878 // if year, monthnum, or day have been specified, make our query more precise
879 // just in case there are multiple identical _wp_old_slug values
880 if ( get_query_var( 'year' ) ) {
881 $query .= $wpdb->prepare(" AND YEAR(post_date) = %d", get_query_var( 'year' ) );
883 if ( get_query_var( 'monthnum' ) ) {
884 $query .= $wpdb->prepare(" AND MONTH(post_date) = %d", get_query_var( 'monthnum' ) );
886 if ( get_query_var( 'day' ) ) {
887 $query .= $wpdb->prepare(" AND DAYOFMONTH(post_date) = %d", get_query_var( 'day' ) );
890 $id = (int) $wpdb->get_var( $query );
896 $link = get_permalink( $id );
898 if ( get_query_var( 'paged' ) > 1 ) {
899 $link = user_trailingslashit( trailingslashit( $link ) . 'page/' . get_query_var( 'paged' ) );
900 } elseif( is_embed() ) {
901 $link = user_trailingslashit( trailingslashit( $link ) . 'embed' );
905 * Filters the old slug redirect URL.
909 * @param string $link The redirect URL.
911 $link = apply_filters( 'old_slug_redirect_url', $link );
917 wp_redirect( $link, 301 ); // Permanent redirect
923 * Set up global post data.
926 * @since 4.4.0 Added the ability to pass a post ID to `$post`.
928 * @global WP_Query $wp_query Global WP_Query instance.
930 * @param WP_Post|object|int $post WP_Post instance or Post ID/object.
931 * @return bool True when finished.
933 function setup_postdata( $post ) {
936 if ( ! empty( $wp_query ) && $wp_query instanceof WP_Query ) {
937 return $wp_query->setup_postdata( $post );