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

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$querystring|arrayoptional

Array or string of Query parameters.Default: ''

• $attachment_idint

  Attachment post ID. Used for 'attachment' post_type.

• $authorint|string

  Author ID, or comma-separated list of IDs.

• $author_namestring

  User 'user_nicename'.

• $author__inint[]

  An array of author IDs to query from.

• $author__not_inint[]

  An array of author IDs not to query from.

• $cache_resultsbooldefault: true

  Whether to cache post information.

• $catint|string

  Category ID or comma-separated list of IDs (this or any children).

• $category__andint[]

  An array of category IDs (AND in).

• $category__inint[]

  An array of category IDs (OR in, no children).

• $category__not_inint[]

  An array of category IDs (NOT in).

• $category_namestring

  Use category slug (not name, this or any children).

• $comment_countarray|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_statusstring

  Comment status.

• $comments_per_pageintdefault: 'comments_per_page' option

  The number of comments to return per page.

• $date_queryarray

  An associative array of WP_Date_Query arguments. See WP_Date_Query::</strong>construct().

• $dayintdefault: empty. Accepts numbers 1-31

  Day of the month.

• $exactbooldefault: false

  Whether to search by exact keyword.

• $fieldsstringdefault: ''

  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[]).

• $hourintdefault: empty. Accepts numbers 0-23

  Hour of the day.

• $ignore_sticky_postsint|booldefault: false

  Whether to ignore sticky posts or not. Setting this to false excludes stickies from 'post__in'. Accepts 1|true, 0|false.

• $mintdefault: empty

  Combination YearMonth. Accepts any four-digit year and month numbers 01-12.

• $meta_keystring|string[]

  Meta key or keys to filter by.

• $meta_valuestring|string[]

  Meta value or values to filter by.

• $meta_comparestring

  MySQL operator used for comparing the meta value. See WP_Meta_Query::construct() for accepted values and default value.

• $meta_compare_keystring

  MySQL operator used for comparing the meta key. See WP_Meta_Query::</strong>construct() for accepted values and default value.

• $meta_typestring

  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_keystring

  MySQL data type that the meta_key column will be CAST to for comparisons. See WP_Meta_Query::</strong>construct() for accepted values and default value.

• $meta_queryarray

  An associative array of WP_Meta_Query arguments. See WP_Meta_Query::construct() for accepted values.

• $menu_orderint

  The menu order of the posts.

• $minuteintdefault: empty. Accepts numbers 0-59

  Minute of the hour.

• $monthnumintdefault: empty. Accepts numbers 1-12

  The two-digit month.

• $namestring

  Post slug.

• $nopagingbooldefault: false

  Show all posts (true) or paginate (false).

• $no_found_rowsbooldefault: false

  Whether to skip counting the total rows found. Enabling can improve performance.

• $offsetint

  The number of posts to offset before retrieval.

• $orderstringdefault: 'DESC'. Accepts 'ASC', 'DESC'

  Designates ascending or descending order of posts.

• $orderbystring|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'.

• $pint

  Post ID.

• $pageint

  Show the number of posts that would show up on page X of a static front page.

• $pagedint

  The number of the current page.

• $page_idint

  Page ID.

• $pagenamestring

  Page slug.

• $permstring

  Show posts if user has the appropriate capability.

• $ping_statusstring

  Ping status.

• $post__inint[]

  An array of post IDs to retrieve, sticky posts will be included.

• $post__not_inint[]

  An array of post IDs not to retrieve. Note: a string of comma- separated IDs will NOT work.

• $post_mime_typestring

  The mime type of the post. Used for 'attachment' post_type.

• $post_name__instring[]

  An array of post slugs that results must match.

• $post_parentint

  Page ID to retrieve child pages for. Use 0 to only retrieve top-level pages.

• $post_parent__inint[]

  An array containing parent page IDs to query child pages from.

• $post_parent__not_inint[]

  An array containing parent page IDs not to query child pages from.

• $post_typestring|string[]default: 'any' if using 'tax_query'

  A post type slug (string) or array of post type slugs.

• $post_statusstring|string[]

  A post status (string) or array of post statuses.

• $posts_per_pageint

  The number of posts to query for. Use -1 to request all posts.

• $posts_per_archive_pageint

  The number of posts to query for by archive page. Overrides 'posts_per_page' when is_archive(), or is_search() are true.

• $sstring

  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.

• $search_columnsstring[]default: empty array

  Array of column names to be searched. Accepts 'post_title', 'post_excerpt' and 'post_content'.

• $secondintdefault: empty. Accepts numbers 0-59

  Second of the minute.

• $sentencebooldefault: false

  Whether to search by phrase.

• $suppress_filtersbooldefault: false

  Whether to suppress filters.

• $tagstring

  Tag slug. Comma-separated (either), Plus-separated (all).

• $tag__andint[]

  An array of tag IDs (AND in).

• $tag__inint[]

  An array of tag IDs (OR in).

• $tag__not_inint[]

  An array of tag IDs (NOT in).

• $tag_idint

  Tag id or comma-separated list of IDs.

• $tag_slug__andstring[]

  An array of tag slugs (AND in).

• $tag_slug__instring[]

  An array of tag slugs (OR in). unless 'ignore_sticky_posts' is true. Note: a string of comma-separated IDs will NOT work.

• $tax_queryarray

  An associative array of WP_Tax_Query arguments. See WP_Tax_Query::__construct().

• $titlestring

  Post title.

• $update_post_meta_cachebooldefault: true

  Whether to update the post meta cache.

• $update_post_term_cachebooldefault: true

  Whether to update the post term cache.

• $update_menu_item_cachebooldefault: false

  Whether to update the menu item cache.

• $lazy_load_term_metabool

  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.

• $wintdefault: empty. Accepts numbers 0-53

  The week number of the year.

• $yearintdefault: empty. Accepts any four-digit year

  The four-digit year.

Performance profile

How much work a call to WP_Query::parse_query() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_post().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

215–252

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 842.

Plugin surface

1 hook

Third-party callbacks on 'parse_query' run inside this call, and their cost is not bounded by anything here.

Called by

2

2 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• optionoption read or writeget_option()called directly
• hookthird-party callbacksdo_action_ref_array()called directly
• serializeserialisationserialize()called directly
• cacheobject cachewp_cache_get()one call below WP_Query::parse_query()
• querycontent queryget_post()one call below WP_Query::parse_query()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 8 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost WP_Query::parse_query() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 1

One hook fires while WP_Query::parse_query() runs, in this order:

1. 1
   do_action( parse_query )actionline 1140 (+349 into the body)

   Fires after the main query vars have been parsed.

Uses · 16

• wp_parse_args()Merges user defined arguments into defaults array.
• absint()Converts a value to non-negative integer.
• wp_checkdate()Tests if the supplied date is valid for the Gregorian calendar.
• get_post_type_object()Retrieves a post type object by name.
• is_admin()Determines whether the current request is for an administrative interface page.
• str_contains()Polyfill for `str_contains()` function added in PHP 8.0.
• wp_is_serving_rest_request()Determines whether WordPress is currently serving a REST API request.
• get_option()Retrieves an option value based on an option name.
• get_page_by_path()Retrieves a page given its path.
• sanitize_key()Sanitizes a string key.
• do_action_ref_array()Calls the callback functions that have been added to an action hook, specifying arguments in an array.
• WP_Query::init()Initiates object properties and sets default values.

Used by · 2

• WP_Query::get_posts()Retrieves an array of posts based on query variables.
• WP_Query::parse_query_vars()Reparses the query vars.

Source code

View on Trac ↗View on GitHub ↗

791	public function parse_query( $query = '' ) {792		if ( ! empty( $query ) ) {793			$this->init();794			$this->query      = wp_parse_args( $query );795			$this->query_vars = $this->query;796		} elseif ( ! isset( $this->query ) ) {797			$this->query = $this->query_vars;798		}799 800		$this->query_vars         = $this->fill_query_vars( $this->query_vars );801		$qv                       = &$this->query_vars;802		$this->query_vars_changed = true;803 804		if ( ! empty( $qv['robots'] ) ) {805			$this->is_robots = true;806		} elseif ( ! empty( $qv['favicon'] ) ) {807			$this->is_favicon = true;808		}809 810		if ( ! is_scalar( $qv['p'] ) || (int) $qv['p'] < 0 ) {811			$qv['p']     = 0;812			$qv['error'] = '404';813		} else {814			$qv['p'] = (int) $qv['p'];815		}816 817		$qv['page_id']  = is_scalar( $qv['page_id'] ) ? absint( $qv['page_id'] ) : 0;818		$qv['year']     = is_scalar( $qv['year'] ) ? absint( $qv['year'] ) : 0;819		$qv['monthnum'] = is_scalar( $qv['monthnum'] ) ? absint( $qv['monthnum'] ) : 0;820		$qv['day']      = is_scalar( $qv['day'] ) ? absint( $qv['day'] ) : 0;821		$qv['w']        = is_scalar( $qv['w'] ) ? absint( $qv['w'] ) : 0;822		$qv['m']        = is_scalar( $qv['m'] ) ? preg_replace( '|[^0-9]|', '', $qv['m'] ) : '';823		$qv['paged']    = is_scalar( $qv['paged'] ) ? absint( $qv['paged'] ) : 0;824		$qv['cat']      = preg_replace( '|[^0-9,-]|', '', $qv['cat'] ); // Array or comma-separated list of positive or negative integers.825		$qv['author']   = is_scalar( $qv['author'] ) ? preg_replace( '|[^0-9,-]|', '', $qv['author'] ) : ''; // Comma-separated list of positive or negative integers.826		$qv['pagename'] = is_scalar( $qv['pagename'] ) ? trim( $qv['pagename'] ) : '';827		$qv['name']     = is_scalar( $qv['name'] ) ? trim( $qv['name'] ) : '';828		$qv['title']    = is_scalar( $qv['title'] ) ? trim( $qv['title'] ) : '';829 830		if ( is_scalar( $qv['hour'] ) && '' !== $qv['hour'] ) {831			$qv['hour'] = absint( $qv['hour'] );832		} else {833			$qv['hour'] = '';834		}835 836		if ( is_scalar( $qv['minute'] ) && '' !== $qv['minute'] ) {837			$qv['minute'] = absint( $qv['minute'] );838		} else {839			$qv['minute'] = '';840		}841 842		if ( is_scalar( $qv['second'] ) && '' !== $qv['second'] ) {843			$qv['second'] = absint( $qv['second'] );844		} else {845			$qv['second'] = '';846		}847 848		if ( is_scalar( $qv['menu_order'] ) && '' !== $qv['menu_order'] ) {849			$qv['menu_order'] = absint( $qv['menu_order'] );850		} else {851			$qv['menu_order'] = '';852		}853 854		// Fairly large, potentially too large, upper bound for search string lengths.855		if ( ! is_scalar( $qv['s'] ) || ( ! empty( $qv['s'] ) && strlen( $qv['s'] ) > 1600 ) ) {856			$qv['s'] = '';857		}858 859		// Compat. Map subpost to attachment.860		if ( is_scalar( $qv['subpost'] ) && '' != $qv['subpost'] ) {861			$qv['attachment'] = $qv['subpost'];862		}863		if ( is_scalar( $qv['subpost_id'] ) && '' != $qv['subpost_id'] ) {864			$qv['attachment_id'] = $qv['subpost_id'];865		}866 867		$qv['attachment_id'] = is_scalar( $qv['attachment_id'] ) ? absint( $qv['attachment_id'] ) : 0;868 869		if ( ( '' !== $qv['attachment'] ) || ! empty( $qv['attachment_id'] ) ) {870			$this->is_single     = true;

Changelog

Introduced in 6.2.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.7.7 tag, from src/wp-includes/class-wp-query.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.