Difference between revisions of "WordPress Query Vars"

Latest revision as of 12:51, 25 March 2023

Languages: English • 日本語 (Add your language)

Query vars define a query for WordPress posts.

When ugly permalinks are enabled, query variables can be seen in the URL. For example, in the URL http://example.com/?p=1 the p query var is set to 1, which will display the single post with an ID of 1.

When pretty permalinks are enabled, URLs don't include query variables. Instead, WordPress transforms the URL into query vars via the Rewrite API, which are used to populate the query.

Relationship to WP_Query

Query vars are fed into WP_Query, WordPress' post querying API.

List of Query Vars

Public

attachment
attachment_id
author
author_name
cat
calendar
category_name
comments_popup
cpage
day
error
exact
feed
hour
m
minute
monthnum
more
name
order
orderby
p
page_id
page
paged
pagename
pb
post_type
posts
preview
robots
s
search
second
sentence
static
subpost
subpost_id
taxonomy
tag
tag_id
tb
term
w
withcomments
withoutcomments
year

Private

category__in
category__not_in
category__and
comments_per_page
offset
perm
post__in
post__not_in
post_mime_type
post_parent__in
tag__and
tag__in
tag__not_in
tag_id
tag_slug__and
tag_slug__in
meta_key
meta_value

Public vs. Private query vars

Public query vars can be used in the URL querystring. Private query vars cannot.

Private query vars can only be used when creating a query in PHP. For example,

<?php

$query = new WP_Query(array(
	'post__in' => array(3, 7)
));

works, but visiting http://example.com/?post__in=3,7 would not work.

@@ Line 1: / Line 1: @@
-= Query Vars =
-An array of query vars are available for WordPress users or developers to utilise in order to query for particular types of content or to aid in theme and/or plugin design and functionality.
-Public query vars are those available and usable via a direct URL query in the form of.
+{{Languages|
+{{en|WordPress_Query_Vars}}
+{{ja|WordPress_Query_Vars}}
+}}
- example.net/?var1=value1&var2=value2
+Query vars define a query for WordPress posts.
-Private query vars cannot be used in the URL, although WordPress will accept a query string with private query vars, the values will not be passed into the query and should be placed directly into the query. An example is given below.
+When [https://codex.wordpress.org/Using_Permalinks ugly permalinks are enabled], query variables can be seen in the URL. For example, in the URL <tt>http://example.com/?p=1</tt> the <tt>p</tt> query var is set to 1, which will display the single post with an ID of 1.
- query_posts('privatevar=myvalue');
+When [https://codex.wordpress.org/Using_Permalinks pretty permalinks are enabled], URLs don't include query variables. Instead, WordPress transforms the URL into query vars via the [https://codex.wordpress.org/Rewrite_API Rewrite API], which are used to populate the query.
-: '''Note:''' Query vars are not necessarily the same thing as query args in URLs (e.g., add_query_arg( 'foo' ). Query vars should only be registered for parameters that actually affect the behavior of WP_Query, and not just for any value passed in the URL. See [http://core.trac.wordpress.org/ticket/16373 #16373] for details.
+== Relationship to WP_Query ==
-== Query Examples ==
+Query vars are fed into [https://codex.wordpress.org/Class_Reference/WP_Query WP_Query], WordPress' post querying API.
-Custom post types and taxonomies can also be queried publicly.
+== List of Query Vars ==
-=== Query Post Type ===
- example.net/?post_type=value1
-In this example, <tt>value1</tt> would be the post type slug you want to query. This would return all posts that match the specified post_type slug.
-=== Query Custom Taxonomy ===
- example.net/?tax1=term1
-In this example, <tt>tax1</tt> is the taxonomy slug and <tt>term1</tt> is the term within that taxonomy that you would like to look up. This would return all posts (regardless of post_type) matching that taxonomy term.
-Queries combining multiple values can be combined to form more complex, granular queries. For instance, to find only posts of a given post type AND taxonomy term, you can specify both.
-== Query variables ==
 <div style="width:370px;float:left;padding:0;background:#f5f5f5;border:1px solid #ddd;margin-right:10px;">
@@ Line 38: / Line 23: @@
 :* <tt>author</tt>
 :* <tt>author_name</tt>
-:* [[Template_Tags/query_posts#Category_Parameters|<tt>cat</tt>]]
+:* <tt>cat</tt>
-:* [[Template_Tags/query_posts#Category_Parameters|<tt>category_name</tt>]]
+:* <tt>calendar</tt>
+:* <tt>category_name</tt>
 :* <tt>comments_popup</tt>
+:* <tt>cpage</tt>
 :* <tt>day</tt>
 :* <tt>error</tt>
+:* <tt>exact</tt>
 :* <tt>feed</tt>
-:* <tt>hour</tt>
 :* <tt>hour</tt>
 :* <tt>m</tt>
 :* <tt>minute</tt>
 :* <tt>monthnum</tt>
+:* <tt>more</tt>
 :* <tt>name</tt>
+:* <tt>order</tt>
+:* <tt>orderby</tt>
 :* <tt>p</tt>
 :* <tt>page_id</tt>
+:* <tt>page</tt>
 :* <tt>paged</tt>
 :* <tt>pagename</tt>
-:* <tt>post_parent</tt>
+:* <tt>pb</tt>
 :* <tt>post_type</tt>
+:* <tt>posts</tt>
 :* <tt>preview</tt>
+:* <tt>robots</tt>
+:* <tt>s</tt>
+:* <tt>search</tt>
 :* <tt>second</tt>
+:* <tt>sentence</tt>
 :* <tt>static</tt>
 :* <tt>subpost</tt>
 :* <tt>subpost_id</tt>
-:* [[Template_Tags/query_posts#Tag_Parameters|<tt>tag</tt>]]
+:* <tt>taxonomy</tt>
-:* [[Template_Tags/query_posts#Tag_Parameters|<tt>tag_id</tt>]]
+:* <tt>tag</tt>
+:* <tt>tag_id</tt>
 :* <tt>tb</tt>
+:* <tt>term</tt>
 :* <tt>w</tt>
+:* <tt>withcomments</tt>
+:* <tt>withoutcomments</tt>
 :* <tt>year</tt>
 </div>
@@ Line 72: / Line 72: @@
 :* <tt>category__not_in</tt>
 :* <tt>category__and</tt>
+:* <tt>comments_per_page</tt>
+:* <tt>offset</tt>
+:* <tt>perm</tt>
 :* <tt>post__in</tt>
 :* <tt>post__not_in</tt>
+:* <tt>post_mime_type</tt>
+:* <tt>post_parent__in</tt>
+:* <tt>tag__and</tt>
 :* <tt>tag__in</tt>
 :* <tt>tag__not_in</tt>
+:* <tt>tag_id</tt>
+:* <tt>tag_slug__and</tt>
+:* <tt>tag_slug__in</tt>
 :* <tt>meta_key</tt>
 :* <tt>meta_value</tt>
 </div>
-<br class="clear" />
-See this list:
+<br class="clear">
+== Public vs. Private query vars ==
-$public_query_vars = array('m', 'p', 'posts', 'w', 'cat', 'withcomments',
+Public query vars can be used in the URL querystring. Private query vars cannot.
-'withoutcomments', 's', 'search', 'exact', 'sentence', 'debug', 'calendar', 'page', 'paged',
-'more', 'tb', 'pb', 'author', 'order', 'orderby', 'year', 'monthnum', 'day', 'hour', 'minute',
-'second', 'name', 'category_name', 'tag', 'feed', 'author_name', 'static', 'pagename',
-'page_id', 'error', 'comments_popup', 'attachment', 'attachment_id', 'subpost',
-'subpost_id', 'preview', 'robots', 'taxonomy', 'term', 'cpage', 'post_type');
-$private_query_vars = array('offset', 'posts_per_page', 'posts_per_archive_page',
-'showposts', 'nopaging', 'post_type', 'post_status', 'category__in', 'category__not_in',
-'category__and', 'tag__in', 'tag__not_in', 'tag__and', 'tag_slug__in', 'tag_slug__and',
-'tag_id', 'post_mime_type', 'perm', 'comments_per_page');
+Private query vars can only be used when creating a query in PHP. For example,
-via http://www.cleancode.co.nz/blog/731/post-data-wordpress-permalink-404
+<pre>
+<?php
-This list needs more work, if you have something to add go ahead.
+$query = new WP_Query(array(
+	'post__in' => array(3, 7)
+));
+</pre>
-{{Stub}}
+works, but visiting <tt>http://example.com/?post__in=3,7</tt> would not work.
-{{Draft}}

Codex