Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Difference between revisions of "WordPress Query Vars"

m (Query variables)
m
 
(9 intermediate revisions by 5 users not shown)
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.
 
   
  +
{{Languages|
Public query vars are those available and usable via a direct URL query in the form of.
 
  +
{{en|WordPress_Query_Vars}}
  +
{{ja|WordPress_Query_Vars}}
  +
}}
   
  +
Query vars define a query for WordPress posts.
example.net/?var1=value1&var2=value2
 
   
  +
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.
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 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.
query_posts('privatevar=myvalue');
 
   
  +
== Relationship to WP_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.
 
   
  +
Query vars are fed into [https://codex.wordpress.org/Class_Reference/WP_Query WP_Query], WordPress' post querying API.
== Query Examples ==
 
   
 
== List of Query Vars ==
Custom post types and taxonomies can also be queried publicly.
 
 
=== 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;">
 
<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</tt>
 
:* <tt>author_name</tt>
 
:* <tt>author_name</tt>
:* [[Template_Tags/query_posts#Category_Parameters|<tt>cat</tt>]]
+
:* <tt>cat</tt>
 
:* <tt>calendar</tt>
:* [[Template_Tags/query_posts#Category_Parameters|<tt>category_name</tt>]]
 
  +
:* <tt>category_name</tt>
 
:* <tt>comments_popup</tt>
 
:* <tt>comments_popup</tt>
  +
:* <tt>cpage</tt>
 
:* <tt>day</tt>
 
:* <tt>day</tt>
 
:* <tt>error</tt>
 
:* <tt>error</tt>
  +
:* <tt>exact</tt>
 
:* <tt>feed</tt>
 
:* <tt>feed</tt>
:* <tt>hour</tt>
 
 
:* <tt>hour</tt>
 
:* <tt>hour</tt>
 
:* <tt>m</tt>
 
:* <tt>m</tt>
 
:* <tt>minute</tt>
 
:* <tt>minute</tt>
 
:* <tt>monthnum</tt>
 
:* <tt>monthnum</tt>
  +
:* <tt>more</tt>
 
:* <tt>name</tt>
 
:* <tt>name</tt>
  +
:* <tt>order</tt>
  +
:* <tt>orderby</tt>
 
:* <tt>p</tt>
 
:* <tt>p</tt>
 
:* <tt>page_id</tt>
 
:* <tt>page_id</tt>
  +
:* <tt>page</tt>
 
:* <tt>paged</tt>
 
:* <tt>paged</tt>
 
:* <tt>pagename</tt>
 
:* <tt>pagename</tt>
:* <tt>post_parent</tt>
+
:* <tt>pb</tt>
 
:* <tt>post_type</tt>
 
:* <tt>post_type</tt>
  +
:* <tt>posts</tt>
 
:* <tt>preview</tt>
 
:* <tt>preview</tt>
  +
:* <tt>robots</tt>
  +
:* <tt>s</tt>
  +
:* <tt>search</tt>
 
:* <tt>second</tt>
 
:* <tt>second</tt>
  +
:* <tt>sentence</tt>
 
:* <tt>static</tt>
 
:* <tt>static</tt>
 
:* <tt>subpost</tt>
 
:* <tt>subpost</tt>
 
:* <tt>subpost_id</tt>
 
:* <tt>subpost_id</tt>
  +
:* <tt>taxonomy</tt>
:* [[Template_Tags/query_posts#Tag_Parameters|<tt>tag</tt>]]
 
  +
:* <tt>tag</tt>
:* [[Template_Tags/query_posts#Tag_Parameters|<tt>tag_id</tt>]]
 
  +
:* <tt>tag_id</tt>
 
:* <tt>tb</tt>
 
:* <tt>tb</tt>
  +
:* <tt>term</tt>
 
:* <tt>w</tt>
 
:* <tt>w</tt>
  +
:* <tt>withcomments</tt>
  +
:* <tt>withoutcomments</tt>
 
:* <tt>year</tt>
 
:* <tt>year</tt>
 
</div>
 
</div>
Line 72: Line 72:
 
:* <tt>category__not_in</tt>
 
:* <tt>category__not_in</tt>
 
:* <tt>category__and</tt>
 
:* <tt>category__and</tt>
  +
:* <tt>comments_per_page</tt>
  +
:* <tt>offset</tt>
  +
:* <tt>perm</tt>
 
:* <tt>post__in</tt>
 
:* <tt>post__in</tt>
 
:* <tt>post__not_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__in</tt>
 
:* <tt>tag__not_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_key</tt>
 
:* <tt>meta_value</tt>
 
:* <tt>meta_value</tt>
 
</div>
 
</div>
<br class="clear" />
 
   
 
<br class="clear">
See this list:
 
  +
  +
== Public vs. Private query vars ==
   
  +
Public query vars can be used in the URL querystring. Private query vars cannot.
$public_query_vars = array('m', 'p', 'posts', 'w', 'cat', 'withcomments',
 
'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,
   
  +
<pre>
via http://www.cleancode.co.nz/blog/731/post-data-wordpress-permalink-404
 
  +
<?php
   
  +
$query = new WP_Query(array(
This list needs more work, if you have something to add go ahead.
 
  +
'post__in' => array(3, 7)
  +
));
  +
</pre>
   
  +
works, but visiting <tt>http://example.com/?post__in=3,7</tt> would not work.
{{Stub}}
 
{{Draft}}
 

Latest revision as of 12:51, 25 March 2023

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.