WP_Query::parse_query() WordPress Method

The WP_Query::parse_query() method is used to parse a query string and set up the WordPress query variables.

WP_Query::parse_query( string|array $query = '' ) #

Parse a query string and set query type booleans.

Contents

Parameters

$query

(string|array)(Optional)Array or string of Query parameters.

  • 'attachment_id'
    (int) Attachment post ID. Used for 'attachment' post_type.
  • 'author'
    (int|string) Author ID, or comma-separated list of IDs.
  • 'author_name'
    (string) User 'user_nicename'.
  • 'author__in'
    (int[]) An array of author IDs to query from.
  • 'author__not_in'
    (int[]) An array of author IDs not to query from.
  • 'cache_results'
    (bool) Whether to cache post information. Default true.
  • 'cat'
    (int|string) Category ID or comma-separated list of IDs (this or any children).
  • 'category__and'
    (int[]) An array of category IDs (AND in).
  • 'category__in'
    (int[]) An array of category IDs (OR in, no children).
  • 'category__not_in'
    (int[]) An array of category IDs (NOT in).
  • 'category_name'
    (string) Use category slug (not name, this or any children).
  • 'comment_count'
    (array|int) Filter results by comment count. Provide an integer to match comment count exactly. Provide an array with integer 'value' and 'compare' operator ('=', '!=', '>', '>=', '<', '<=' ) to compare against comment_count in a specific way.
  • 'comment_status'
    (string) Comment status.
  • 'comments_per_page'
    (int) The number of comments to return per page. Default 'comments_per_page' option.
  • 'date_query'
    (array) An associative array of WP_Date_Query arguments. See WP_Date_Query::__construct().
  • 'day'
    (int) Day of the month. Accepts numbers 1-31.
  • 'exact'
    (bool) Whether to search by exact keyword. Default false.
  • 'fields'
    (string) Post fields to query for. Accepts:
    • '' Returns an array of complete post objects (WP_Post[]).
    • 'ids' Returns an array of post IDs (int[]).
    • 'id=>parent' Returns an associative array of parent post IDs, keyed by post ID (int[]).
  • 'hour'
    (int) Hour of the day. Accepts numbers 0-23.
  • 'ignore_sticky_posts'
    (int|bool) Whether to ignore sticky posts or not. Setting this to false excludes stickies from 'post__in'. Accepts 1|true, 0|false. Default false.
  • 'm'
    (int) Combination YearMonth. Accepts any four-digit year and month numbers 1-12.
  • 'meta_key'
    (string|string[]) Meta key or keys to filter by.
  • 'meta_value'
    (string|string[]) Meta value or values to filter by.
  • 'meta_compare'
    (string) MySQL operator used for comparing the meta value. See WP_Meta_Query::__construct for accepted values and default value.
  • 'meta_compare_key'
    (string) MySQL operator used for comparing the meta key. See WP_Meta_Query::__construct for accepted values and default value.
  • 'meta_type'
    (string) MySQL data type that the meta_value column will be CAST to for comparisons. See WP_Meta_Query::__construct for accepted values and default value.
  • 'meta_type_key'
    (string) MySQL data type that the meta_key column will be CAST to for comparisons. See WP_Meta_Query::__construct for accepted values and default value.
  • 'meta_query'
    (array) An associative array of WP_Meta_Query arguments. See WP_Meta_Query::__construct for accepted values.
  • 'menu_order'
    (int) The menu order of the posts.
  • 'minute'
    (int) Minute of the hour. Accepts numbers 0-59.
  • 'monthnum'
    (int) The two-digit month. Accepts numbers 1-12.
  • 'name'
    (string) Post slug.
  • 'nopaging'
    (bool) Show all posts (true) or paginate (false). Default false.
  • 'no_found_rows'
    (bool) Whether to skip counting the total rows found. Enabling can improve performance. Default false.
  • 'offset'
    (int) The number of posts to offset before retrieval.
  • 'order'
    (string) Designates ascending or descending order of posts. Default 'DESC'. Accepts 'ASC', 'DESC'.
  • 'orderby'
    (string|array) Sort retrieved posts by parameter. One or more options may be passed. To use 'meta_value', or 'meta_value_num', 'meta_key=keyname' must be also be defined. To sort by a specific $meta_query clause, use that clause's array key. Accepts:
  • 'none'
  • 'name'
  • 'author'
  • 'date'
  • 'title'
  • 'modified'
  • 'menu_order'
  • 'parent'
  • 'ID'
  • 'rand'
  • 'relevance'
  • 'RAND(x)' (where 'x' is an integer seed value)
  • 'comment_count'
  • 'meta_value'
  • 'meta_value_num'
  • 'post__in'
  • 'post_name__in'
  • 'post_parent__in'
  • The array keys of $meta_query. Default is 'date', except when a search is being performed, when the default is 'relevance'.
  • 'p'
    (int) Post ID.
  • 'page'
    (int) Show the number of posts that would show up on page X of a static front page.
  • 'paged'
    (int) The number of the current page.
  • 'page_id'
    (int) Page ID.
  • 'pagename'
    (string) Page slug.
  • 'perm'
    (string) Show posts if user has the appropriate capability.
  • 'ping_status'
    (string) Ping status.
  • 'post__in'
    (int[]) An array of post IDs to retrieve, sticky posts will be included.
  • 'post__not_in'
    (int[]) An array of post IDs not to retrieve. Note: a string of comma- separated IDs will NOT work.
  • 'post_mime_type'
    (string) The mime type of the post. Used for 'attachment' post_type.
  • 'post_name__in'
    (string[]) An array of post slugs that results must match.
  • 'post_parent'
    (int) Page ID to retrieve child pages for. Use 0 to only retrieve top-level pages.
  • 'post_parent__in'
    (int[]) An array containing parent page IDs to query child pages from.
  • 'post_parent__not_in'
    (int[]) An array containing parent page IDs not to query child pages from.
  • 'post_type'
    (string|string[]) A post type slug (string) or array of post type slugs. Default 'any' if using 'tax_query'.
  • 'post_status'
    (string|string[]) A post status (string) or array of post statuses.
  • 'posts_per_page'
    (int) The number of posts to query for. Use -1 to request all posts.
  • 'posts_per_archive_page'
    (int) The number of posts to query for by archive page. Overrides 'posts_per_page' when is_archive(), or is_search() are true.
  • 's'
    (string) Search keyword(s). Prepending a term with a hyphen will exclude posts matching that term. Eg, 'pillow -sofa' will return posts containing 'pillow' but not 'sofa'. The character used for exclusion can be modified using the the 'wp_query_search_exclusion_prefix' filter.
  • 'second'
    (int) Second of the minute. Accepts numbers 0-59.
  • 'sentence'
    (bool) Whether to search by phrase. Default false.
  • 'suppress_filters'
    (bool) Whether to suppress filters. Default false.
  • 'tag'
    (string) Tag slug. Comma-separated (either), Plus-separated (all).
  • 'tag__and'
    (int[]) An array of tag IDs (AND in).
  • 'tag__in'
    (int[]) An array of tag IDs (OR in).
  • 'tag__not_in'
    (int[]) An array of tag IDs (NOT in).
  • 'tag_id'
    (int) Tag id or comma-separated list of IDs.
  • 'tag_slug__and'
    (string[]) An array of tag slugs (AND in).
  • 'tag_slug__in'
    (string[]) An array of tag slugs (OR in). unless 'ignore_sticky_posts' is true. Note: a string of comma-separated IDs will NOT work.
  • 'tax_query'
    (array) An associative array of WP_Tax_Query arguments. See WP_Tax_Query->__construct().
  • 'title'
    (string) Post title.
  • 'update_post_meta_cache'
    (bool) Whether to update the post meta cache. Default true.
  • 'update_post_term_cache'
    (bool) Whether to update the post term cache. Default true.
  • 'lazy_load_term_meta'
    (bool) Whether to lazy-load term meta. Setting to false will disable cache priming for term meta, so that each get_term_meta() call will hit the database. Defaults to the value of $update_post_term_cache.
  • 'w'
    (int) The week number of the year. Accepts numbers 0-53.
  • 'year'
    (int) The four-digit year. Accepts any four-digit year.

    • Default value: ''

    Top ↑

    Source

    File: wp-includes/class-wp-query.php

    	public function parse_query( $query = '' ) {
		if ( ! empty( $query ) ) {
			$this->init();
			$this->query      = wp_parse_args( $query );
			$this->query_vars = $this->query;
		} elseif ( ! isset( $this->query ) ) {
			$this->query = $this->query_vars;
		}

		$this->query_vars         = $this->fill_query_vars( $this->query_vars );
		$qv                       = &$this->query_vars;
		$this->query_vars_changed = true;

		if ( ! empty( $qv['robots'] ) ) {
			$this->is_robots = true;
		} elseif ( ! empty( $qv['favicon'] ) ) {
			$this->is_favicon = true;
		}

		if ( ! is_scalar( $qv['p'] ) || (int) $qv['p'] < 0 ) {
			$qv['p']     = 0;
			$qv['error'] = '404';
		} else {
			$qv['p'] = (int) $qv['p'];
		}

		$qv['page_id']  = absint( $qv['page_id'] );
		$qv['year']     = absint( $qv['year'] );
		$qv['monthnum'] = absint( $qv['monthnum'] );
		$qv['day']      = absint( $qv['day'] );
		$qv['w']        = absint( $qv['w'] );
		$qv['m']        = is_scalar( $qv['m'] ) ? preg_replace( '|[^0-9]|', '', $qv['m'] ) : '';
		$qv['paged']    = absint( $qv['paged'] );
		$qv['cat']      = preg_replace( '|[^0-9,-]|', '', $qv['cat'] );    // Comma-separated list of positive or negative integers.
		$qv['author']   = preg_replace( '|[^0-9,-]|', '', $qv['author'] ); // Comma-separated list of positive or negative integers.
		$qv['pagename'] = trim( $qv['pagename'] );
		$qv['name']     = trim( $qv['name'] );
		$qv['title']    = trim( $qv['title'] );
		if ( '' !== $qv['hour'] ) {
			$qv['hour'] = absint( $qv['hour'] );
		}
		if ( '' !== $qv['minute'] ) {
			$qv['minute'] = absint( $qv['minute'] );
		}
		if ( '' !== $qv['second'] ) {
			$qv['second'] = absint( $qv['second'] );
		}
		if ( '' !== $qv['menu_order'] ) {
			$qv['menu_order'] = absint( $qv['menu_order'] );
		}

		// Fairly large, potentially too large, upper bound for search string lengths.
		if ( ! is_scalar( $qv['s'] ) || ( ! empty( $qv['s'] ) && strlen( $qv['s'] ) > 1600 ) ) {
			$qv['s'] = '';
		}

		// Compat. Map subpost to attachment.
		if ( '' != $qv['subpost'] ) {
			$qv['attachment'] = $qv['subpost'];
		}
		if ( '' != $qv['subpost_id'] ) {
			$qv['attachment_id'] = $qv['subpost_id'];
		}

		$qv['attachment_id'] = absint( $qv['attachment_id'] );

		if ( ( '' !== $qv['attachment'] ) || ! empty( $qv['attachment_id'] ) ) {
			$this->is_single     = true;
			$this->is_attachment = true;
		} elseif ( '' !== $qv['name'] ) {
			$this->is_single = true;
		} elseif ( $qv['p'] ) {
			$this->is_single = true;
		} elseif ( '' !== $qv['pagename'] || ! empty( $qv['page_id'] ) ) {
			$this->is_page   = true;
			$this->is_single = false;
		} else {
			// Look for archive queries. Dates, categories, authors, search, post type archives.

			if ( isset( $this->query['s'] ) ) {
				$this->is_search = true;
			}

			if ( '' !== $qv['second'] ) {
				$this->is_time = true;
				$this->is_date = true;
			}

			if ( '' !== $qv['minute'] ) {
				$this->is_time = true;
				$this->is_date = true;
			}

			if ( '' !== $qv['hour'] ) {
				$this->is_time = true;
				$this->is_date = true;
			}

			if ( $qv['day'] ) {
				if ( ! $this->is_date ) {
					$date = sprintf( '%04d-%02d-%02d', $qv['year'], $qv['monthnum'], $qv['day'] );
					if ( $qv['monthnum'] && $qv['year'] && ! wp_checkdate( $qv['monthnum'], $qv['day'], $qv['year'], $date ) ) {
						$qv['error'] = '404';
					} else {
						$this->is_day  = true;
						$this->is_date = true;
					}
				}
			}

			if ( $qv['monthnum'] ) {
				if ( ! $this->is_date ) {
					if ( 12 < $qv['monthnum'] ) {
						$qv['error'] = '404';
					} else {
						$this->is_month = true;
						$this->is_date  = true;
					}
				}
			}

			if ( $qv['year'] ) {
				if ( ! $this->is_date ) {
					$this->is_year = true;
					$this->is_date = true;
				}
			}

			if ( $qv['m'] ) {
				$this->is_date = true;
				if ( strlen( $qv['m'] ) > 9 ) {
					$this->is_time = true;
				} elseif ( strlen( $qv['m'] ) > 7 ) {
					$this->is_day = true;
				} elseif ( strlen( $qv['m'] ) > 5 ) {
					$this->is_month = true;
				} else {
					$this->is_year = true;
				}
			}

			if ( $qv['w'] ) {
				$this->is_date = true;
			}

			$this->query_vars_hash = false;
			$this->parse_tax_query( $qv );

			foreach ( $this->tax_query->queries as $tax_query ) {
				if ( ! is_array( $tax_query ) ) {
					continue;
				}

				if ( isset( $tax_query['operator'] ) && 'NOT IN' !== $tax_query['operator'] ) {
					switch ( $tax_query['taxonomy'] ) {
						case 'category':
							$this->is_category = true;
							break;
						case 'post_tag':
							$this->is_tag = true;
							break;
						default:
							$this->is_tax = true;
					}
				}
			}
			unset( $tax_query );

			if ( empty( $qv['author'] ) || ( '0' == $qv['author'] ) ) {
				$this->is_author = false;
			} else {
				$this->is_author = true;
			}

			if ( '' !== $qv['author_name'] ) {
				$this->is_author = true;
			}

			if ( ! empty( $qv['post_type'] ) && ! is_array( $qv['post_type'] ) ) {
				$post_type_obj = get_post_type_object( $qv['post_type'] );
				if ( ! empty( $post_type_obj->has_archive ) ) {
					$this->is_post_type_archive = true;
				}
			}

			if ( $this->is_post_type_archive || $this->is_date || $this->is_author || $this->is_category || $this->is_tag || $this->is_tax ) {
				$this->is_archive = true;
			}
		}

		if ( '' != $qv['feed'] ) {
			$this->is_feed = true;
		}

		if ( '' != $qv['embed'] ) {
			$this->is_embed = true;
		}

		if ( '' != $qv['tb'] ) {
			$this->is_trackback = true;
		}

		if ( '' != $qv['paged'] && ( (int) $qv['paged'] > 1 ) ) {
			$this->is_paged = true;
		}

		// If we're previewing inside the write screen.
		if ( '' != $qv['preview'] ) {
			$this->is_preview = true;
		}

		if ( is_admin() ) {
			$this->is_admin = true;
		}

		if ( false !== strpos( $qv['feed'], 'comments-' ) ) {
			$qv['feed']         = str_replace( 'comments-', '', $qv['feed'] );
			$qv['withcomments'] = 1;
		}

		$this->is_singular = $this->is_single || $this->is_page || $this->is_attachment;

		if ( $this->is_feed && ( ! empty( $qv['withcomments'] ) || ( empty( $qv['withoutcomments'] ) && $this->is_singular ) ) ) {
			$this->is_comment_feed = true;
		}

		if ( ! ( $this->is_singular || $this->is_archive || $this->is_search || $this->is_feed
				|| ( defined( 'REST_REQUEST' ) && REST_REQUEST && $this->is_main_query() )
				|| $this->is_trackback || $this->is_404 || $this->is_admin || $this->is_robots || $this->is_favicon ) ) {
			$this->is_home = true;
		}

		// Correct `is_*` for 'page_on_front' and 'page_for_posts'.
		if ( $this->is_home && 'page' === get_option( 'show_on_front' ) && get_option( 'page_on_front' ) ) {
			$_query = wp_parse_args( $this->query );
			// 'pagename' can be set and empty depending on matched rewrite rules. Ignore an empty 'pagename'.
			if ( isset( $_query['pagename'] ) && '' === $_query['pagename'] ) {
				unset( $_query['pagename'] );
			}

			unset( $_query['embed'] );

			if ( empty( $_query ) || ! array_diff( array_keys( $_query ), array( 'preview', 'page', 'paged', 'cpage' ) ) ) {
				$this->is_page = true;
				$this->is_home = false;
				$qv['page_id'] = get_option( 'page_on_front' );
				// Correct <!--nextpage--> for 'page_on_front'.
				if ( ! empty( $qv['paged'] ) ) {
					$qv['page'] = $qv['paged'];
					unset( $qv['paged'] );
				}
			}
		}

		if ( '' !== $qv['pagename'] ) {
			$this->queried_object = get_page_by_path( $qv['pagename'] );

			if ( $this->queried_object && 'attachment' === $this->queried_object->post_type ) {
				if ( preg_match( '/^[^%]*%(?:postname)%/', get_option( 'permalink_structure' ) ) ) {
					// See if we also have a post with the same slug.
					$post = get_page_by_path( $qv['pagename'], OBJECT, 'post' );
					if ( $post ) {
						$this->queried_object = $post;
						$this->is_page        = false;
						$this->is_single      = true;
					}
				}
			}

			if ( ! empty( $this->queried_object ) ) {
				$this->queried_object_id = (int) $this->queried_object->ID;
			} else {
				unset( $this->queried_object );
			}

			if ( 'page' === get_option( 'show_on_front' ) && isset( $this->queried_object_id ) && get_option( 'page_for_posts' ) == $this->queried_object_id ) {
				$this->is_page       = false;
				$this->is_home       = true;
				$this->is_posts_page = true;
			}

			if ( isset( $this->queried_object_id ) && get_option( 'wp_page_for_privacy_policy' ) == $this->queried_object_id ) {
				$this->is_privacy_policy = true;
			}
		}

		if ( $qv['page_id'] ) {
			if ( 'page' === get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) == $qv['page_id'] ) {
				$this->is_page       = false;
				$this->is_home       = true;
				$this->is_posts_page = true;
			}

			if ( get_option( 'wp_page_for_privacy_policy' ) == $qv['page_id'] ) {
				$this->is_privacy_policy = true;
			}
		}

		if ( ! empty( $qv['post_type'] ) ) {
			if ( is_array( $qv['post_type'] ) ) {
				$qv['post_type'] = array_map( 'sanitize_key', $qv['post_type'] );
			} else {
				$qv['post_type'] = sanitize_key( $qv['post_type'] );
			}
		}

		if ( ! empty( $qv['post_status'] ) ) {
			if ( is_array( $qv['post_status'] ) ) {
				$qv['post_status'] = array_map( 'sanitize_key', $qv['post_status'] );
			} else {
				$qv['post_status'] = preg_replace( '|[^a-z0-9_,-]|', '', $qv['post_status'] );
			}
		}

		if ( $this->is_posts_page && ( ! isset( $qv['withcomments'] ) || ! $qv['withcomments'] ) ) {
			$this->is_comment_feed = false;
		}

		$this->is_singular = $this->is_single || $this->is_page || $this->is_attachment;
		// Done correcting `is_*` for 'page_on_front' and 'page_for_posts'.

		if ( '404' == $qv['error'] ) {
			$this->set_404();
		}

		$this->is_embed = $this->is_embed && ( $this->is_singular || $this->is_404 );

		$this->query_vars_hash    = md5( serialize( $this->query_vars ) );
		$this->query_vars_changed = false;

		/**
		 * Fires after the main query vars have been parsed.
		 *
		 * @since 1.5.0
		 *
		 * @param WP_Query $query The WP_Query instance (passed by reference).
		 */
		do_action_ref_array( 'parse_query', array( &$this ) );
	}

    Expand full source codeCollapse full source codeView on TracView on GitHub

    Top ↑

    Top ↑

    Uses

    Uses
    UsesDescription
    wp-includes/formatting.php:sanitize_key()

    Sanitizes a string key.

    wp-includes/class-wp-query.php:WP_Query::is_main_query()

    Is the query the main query?

    wp-includes/class-wp-query.php:WP_Query::set_404()

    Sets the 404 property and saves whether query is feed.

    wp-includes/class-wp-query.php:WP_Query::init()

    Initiates object properties and sets default values.

    wp-includes/class-wp-query.php:WP_Query::fill_query_vars()

    Fills in the query variables, which do not exist within the parameter.

    wp-includes/class-wp-query.php:WP_Query::parse_tax_query()

    Parses various taxonomy related query vars.

    wp-includes/class-wp-query.php:parse_query

    Fires after the main query vars have been parsed.

    wp-includes/load.php:is_admin()

    Determines whether the current request is for an administrative interface page.

    wp-includes/functions.php:wp_checkdate()

    Test if the supplied date is valid for the Gregorian calendar.

    wp-includes/functions.php:wp_parse_args()

    Merges user defined arguments into defaults array.

    wp-includes/functions.php:absint()

    Convert a value to non-negative integer.

    wp-includes/plugin.php:do_action_ref_array()

    Calls the callback functions that have been added to an action hook, specifying arguments in an array.

    wp-includes/option.php:get_option()

    Retrieves an option value based on an option name.

    wp-includes/post.php:get_page_by_path()

    Retrieves a page given its path.

    wp-includes/post.php:get_post_type_object()

    Retrieves a post type object by name.

    Show 10 more usesHide more uses

    Top ↑

    Changelog

    Changelog
    VersionDescription
    5.3.0Introduced the $meta_type_key parameter.
    5.1.0Introduced the $meta_compare_key parameter.
    4.9.0Introduced the $comment_count parameter.
    4.6.0Added 'post_name__in' support for $orderby. Introduced the $lazy_load_term_meta argument.
    4.5.0Removed the $comments_popup parameter. Introduced the $comment_status and $ping_status parameters. Introduced RAND(x) syntax for $orderby, which allows an integer seed value to random sorts.
    4.4.0Introduced $post_name__in and $title parameters. $s was updated to support excluded search terms, by prepending a hyphen.
    4.2.0Introduced the ability to order by specific clauses of a $meta_query, by passing the clause's array key to $orderby.
    1.5.0Introduced.
    Download the latest version of WordPress from https://wordpress.org/

    The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by the Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.

    Show More