Skip to content

Instantly share code, notes, and snippets.

@apintocr

apintocr/wp-query-ref.php

Created February 11, 2017 15:27
Show Gist options
  • Save apintocr/7047d067d32ef005b156a1f102c626d2 to your computer and use it in GitHub Desktop.
Save apintocr/7047d067d32ef005b156a1f102c626d2 to your computer and use it in GitHub Desktop.
Download ZIP
WP: Query $args
Raw
wp-query-ref.php
<?php
/**
* WordPress Query Comprehensive Reference.
*
* All credits go to luetkemj. Thanks!
*
* @author luetkemj <[email protected]>
* @author s3rgiosan <[email protected]>
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Parameters
* @see https://core.trac.wordpress.org/browser/tags/3.9/src/wp-includes/query.php
*/
$args = array(
/**
* Author Parameters.
*
* Show posts associated with certain author.
*
* @since 3.7 'author__in', 'author__not_in'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Author_Parameters
*/
'author' => '1,2,3,', // int Use author id [use minus (-) to exclude authors by ID ex. 'author' => '-1,-2,-3,']
'author_name' => 'luetkemj', // string Use 'user_nicename' (NOT name)
'author__in' => array( 2, 6 ), // array Use author id.
'author__not_in' => array( 2, 6 ), // array Use author id.
/**
* Category Parameters.
*
* Show posts associated with certain categories.
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Category_Parameters
*/
'cat' => 5, // int Use category id.
'category_name' => 'staff, news', // string Display posts that have these categories, using category slug.
'category_name' => 'staff+news', // string Display posts that have "all" of these categories, using category slug.
'category__and' => array( 2, 6 ), // array Use category id.
'category__in' => array( 2, 6 ), // array Use category id.
'category__not_in' => array( 2, 6 ), // array Use category id.
/**
* Tag Parameters.
*
* Show posts associated with certain tags.
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Tag_Parameters
*/
'tag' => 'cooking', // string Use tag slug.
'tag_id' => 5, // int Use tag id.
'tag__and' => array( 2, 6 ), // array Use tag ids.
'tag__in' => array( 2, 6 ), // array Use tag ids.
'tag__not_in' => array( 2, 6 ), // array Use tag ids.
'tag_slug__and' => array( 'red', 'blue' ), // array Use tag slugs.
'tag_slug__in' => array( 'red', 'blue' ), // array Use tag slugs.
/**
* Taxonomy Parameters.
*
* Show posts associated with certain taxonomy.
*
* Note:
* - tax_query takes an array of tax query arguments arrays (it takes an array of arrays).
* This construct allows you to query multiple taxonomies by using the relation parameter in the
* first (outer) array to describe the boolean relationship between the taxonomy queries.
*
* @since 3.1 'tax_query'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Taxonomy_Parameters
*/
'tax_query' => array( // array Use taxonomy parameters.
'relation' => 'AND', // string Possible values are 'AND' or 'OR' and is the
// equivalent of running a JOIN for each taxonomy.
array(
'taxonomy' => 'color', // string Taxonomy.
'field' => 'slug', // string Select taxonomy term by ('id' or 'slug').
'terms' => array( 'red', 'blue' ), // int|string|array Taxonomy term(s).
'include_children' => true, // bool Whether or not to include children for
// hierarchical taxonomies. Defaults to true.
'operator' => 'IN' // string Operator to test. Possible values are 'IN', 'NOT IN', 'AND'.
),
array(
'taxonomy' => 'actor',
'field' => 'id',
'terms' => array( 103, 115, 206 ),
'include_children' => false,
'operator' => 'NOT IN'
)
),
/**
* Post & Page Parameters.
*
* Display content based on post and page parameters.
*
* Note:
* - you cannot combine 'post__in' and 'post__not_in' in the same query
*
* @since 3.6 'post_parent__in'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Post_.26_Page_Parameters
*/
'p' => 1, // int Use post id.
'name' => 'hello-world', // string Use post slug.
'page_id' => 1, // int Use page id.
'pagename' => 'sample-page', // string Use page slug.
'pagename' => 'contact_us/canada', // string Display child page using the slug of the parent and the child page, separated ba slash.
'post_parent' => 1, // int Use page id. Return just the child Pages. (Only works with hierarchical post types).
'post_parent__in' => array( 1, 2, 3 ), // array Use post ids. Specify posts whose parent is in an array.
'post_parent__not_in' => array( 1, 2, 3 ), // array Use post ids. Specify posts whose parent is not in an array.
'post__in' => array( 1, 2, 3 ), // array Use post ids. Specify posts to retrieve.
// If you use sticky posts, they will be included (prepended!) in the posts you retrieve
// whether you want it or not. To suppress this behaviour use ignore_sticky_posts
'post__not_in' => array( 1, 2, 3 ), // array Use post ids. Specify post NOT to retrieve.
/**
* Password Parameters.
*
* Show content based on post and page parameters.
* Remember that default post_type is only set to display posts but not pages.
*
* @since 3.9 'has_password', 'post_password'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Password_Parameters
*/
'has_password' => true, // bool|null True for posts with passwords, false otherwise.
// Null for all posts with and without passwords
'post_password' => 'multi-pass', // string Show posts with a particular password.
/**
* Type & Status Parameters.
*
* Show posts associated with certain type or status.
*
* Note:
* - The 'any' keyword available to both post_type and post_status queries cannot be used within an array.
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Type_Parameters
*/
'post_type' => array( // string|array Use post types. Retrieves posts by Post Types, default value is 'post'.
'post',
'page',
'revision',
'attachment', // The default WP_Query sets 'post_status' => 'published', but attachments default to
// 'post_status' => 'inherit' so you'll need to set the status to 'inherit' or 'any'.
'custom-post-type',
),
'post_type' => 'any', // Retrieves any type except revisions and types with 'exclude_from_search' set to true.
/**
* Type & Status Parameters.
*
* Show posts associated with certain type or status.
*
* Note:
* - The 'any' keyword available to both post_type and post_status queries cannot be used within an array.
*
* @since 2.9 'trash'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Status_Parameters
*/
'post_status' => array( // string|array Use post status. Retrieves posts by Post Status, default value is 'publish'.
'publish',
'pending',
'draft',
'auto-draft',
'future',
'private',
'inherit',
'trash'
),
'post_status' => 'any', // Retrieves any status except those from post types with 'exclude_from_search' set to true.
/**
* Pagination Parameters.
*
* Note:
* -
*
* @since 3.1 'ignore_sticky_posts'
* @since 2.1 'posts_per_page'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Pagination_Parameters
*/
'posts_per_page' => 10, // int Number of post to show per page.
// Use 'posts_per_page' = -1 to show all posts. Note if the query is in a feed,
// wordpress overwrites this parameter with the stored 'posts_per_rss' option.
// Treimpose the limit, try using the 'post_limits' filter, or filter
// 'pre_option_posts_per_rss' and return -1.
'posts_per_archive_page' => 10, // int Number of posts to show per page - on archive pages only.
// Overrides 'showposts' and 'posts_per_page' on pages where is_archive() or
// is_search() would be true.
'nopaging' => false, // bool Show all posts or use pagination. Default value is 'false', use paging.
'paged' => get_query_var( 'paged' ), // int Number of page. Show the posts that would normally show up just on page X
// when using the "Older Entries" link.
'nopaging' => false, // bool Show all posts or use pagination. Default value is 'false', use paging.
// The 'offset' parameter is ignored when 'posts_per_page'=>-1 (show all posts) is used.
'page' => get_query_var( 'page' ), // int Number of page for a static front page. Show the posts that would
// normally show up just on page X of a Static Front Page.
'ignore_sticky_posts' => false, // bool Ignore sticky posts or not. Default value is 0 - don't ignore sticky posts.
/**
* Order & Orderby Parameters.
*
* Sort retrieved posts.
*
* @since 3.5 'post__in'
* @since 2.9 'comment_count'
* @since 2.8 'none', 'meta_value_num'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Order_.26_Orderby_Parameters
*/
'order' => 'DESC', // string Designates the ascending or descending order of the 'orderby' parameter. Default to 'DESC'.
// Possible Values:
// 'ASC' - ascending order from lowest to highest values (1, 2, 3; a, b, c).
// 'DESC' - descending order from highest to lowest values (3, 2, 1; c, b, a).
'orderby' => 'date', // string Sort retrieved posts by parameter. Defaults to 'date'.
// One or more options can be passed. Ex: 'orderby' => 'menu_order title'
// Possible Values:
// 'none' - No order.
// 'ID' - Order by post id. Note the captialization.
// 'author' - Order by author.
// 'title' - Order by title.
// 'name' - Order by post name (post slug).
// 'date' - Order by date.
// 'modified' - Order by last modified date.
// 'parent' - Order by post/page parent id.
// 'rand' - Random order.
// 'comment_count' - Order by number of comments.
// 'menu_order' - Order by Page Order. Used most often for Pages (Order field in the Edit Page Attributes box)
// and for Attachments (the integer fields in the Insert / Upload Media Gallery dialog),
// but could be used for any post type with distinct 'menu_order' values (they all default to 0).
// 'meta_value' - Note that a 'meta_key=keyname' must also be present in the query. Note also that the sorting
// will be alphabetical which is fine for strings (i.e. words), but can be unexpected for numbers
// (e.g. 1, 3, 34, 4, 56, 6, etc, rather than 1, 3, 4, 6, 34, 56 as you might naturally expect).
// 'meta_value_num' - Order by numeric meta value. Also not that a 'meta_key=keyname' must also be present in the query.
// This value allows for numeric asorting as noted above in 'meta_value'.
// 'title menu_order' - Order by both menu_order AND title at the same time.
// 'post__in' - Preserve post ID order given in the post__in array.
/**
* Date Parameters.
*
* Show posts associated with a certain time and date period.
*
* @since 3.7 'date_query'
* @since 3.5 'meta_qdate_queryuery' with 'compare' values of 'EXISTS' and 'NOT EXISTS'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Date_Parameters
*/
'year' => 2014, // int 4 digit year (e.g. 2011).
'monthnum' => 4, // int Month number (from 1 to 12).
'w' => 25, // int Week of the year (from 0 to 53). Uses the MySQL WEEK command. The mode is dependenon the 'start_of_week' option.
'day' => 17, // int Day of the month (from 1 to 31).
'hour' => 13, // int Hour (from 0 to 23).
'minute' => 19, // int Minute (from 0 to 60).
'second' => 30, // int Second (0 to 60).
'm' => 201404, // int YearMonth (For e.g.: 201307).
'date_query' => array( // array Date parameters.
array(
'year' => 2014, // int 4 digit year (e.g. 2011).
'month' => 4 // int Month number (from 1 to 12).
'week' => 31 // int Week of the year (from 0 to 53).
'day' => 5 // int Day of the month (from 1 to 31).
'hour' => 2 // int Hour (from 0 to 23).
'minute' => 3 // int Minute (from 0 to 59).
'second' => 36 // int Second (0 to 59).
'after' => 'January 1st, 2013', // string|array Date to retrieve posts after.
// Accepts strtotime()-compatible string, or array of 'year', 'month', 'day'
'before' => array( // string|array Date to retrieve posts before.
// Accepts strtotime()-compatible string, or array of 'year', 'month', 'day'
'year' => 2013, // string Accepts any four-digit year. Default value is empty.
'month' => 2, // string The month of the year. Accepts numbers 1-12. Default: 12.
'day' => 28, // string The day of the month. Accepts numbers 1-31. Default: last day of month.
),
'inclusive' => true, // bool For after/before, whether exact value should be matched or not'.
'compare' => '=', // string Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE',
// 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS', and 'NOT EXISTS'.
// Default value is '='
'column' => 'post_date', // string Column to query against. Default: 'post_date'.
'relation' => 'AND', // string OR or AND, how the sub-arrays should be compared. Default: AND.
),
),
/**
* Custom Field Parameters.
*
* Show posts associated with a certain custom field.
*
* @since 3.5 'meta_query' with 'compare' values of 'EXISTS' and 'NOT EXISTS'
* @since 3.1 'meta_query'
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Custom_Field_Parameters
*/
'meta_key' => 'key', // string Custom field key.
'meta_value' => 'value', // string Custom field value.
'meta_value_num' => 10, // int Custom field value.
'meta_compare' => '=', // string Operator to test the 'meta_value'. Possible values are '!=', '>', '>=', '<', or ='.
// Default value is '='.
'meta_query' => array( // array Custom field parameters
'relation' => 'AND', // string Possible values are 'AND', 'OR'.
// The logical relationship between each inner meta_query array when there is more than one.
// Do not use with a single inner meta_query array.
array(
'key' => 'color', // string Custom field key.
'value' => 'blue' // string|array Custom field value.
// Array support is limited to a compare value of 'IN', 'NOT IN', 'BETWEEN', or 'NOT BETWEEN'.
'type' => 'CHAR', // string Custom field type. Possible values are 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME',
// 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'. Default value is 'CHAR'.
// The 'type' DATE works with the 'compare' value BETWEEN only if the date is stored at the
// format YYYYMMDD and tested with this format.
'compare' => '=' // string Operator to test. Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE',
// 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS', and 'NOT EXISTS'.
// Default value is '='.
),
),
/**
* Permission Parameters.
*
* Display published posts, as well as private posts, if the user has the appropriate capability.
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Permission_Parameters
*/
'perm' => 'readable' // string Possible values are 'readable', 'editable'
/**
* Caching Parameters.
*
* Note:
* - Caching is a good thing. Setting these to false is generally not advised.
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Caching_Parameters
*/
'cache_results' => true, // bool Post information cache. Default value is true.
'update_post_term_cache' => true, // bool Post meta information cache. Default value is true.
'update_post_meta_cache' => true, // bool Post term information cache. Default value is true.
'no_found_rows' => false, // bool WordPress uses SQL_CALC_FOUND_ROWS in most queries in order to implement pagination.
// Even when you don’t need pagination at all. By Setting this parameter to true you are telling
// wordPress not to count the total rows and reducing load on the DB. Pagination will NOT WORK
// when this parameter is set to true. Default value is false.
/**
* Search Parameter.
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Search_Parameter
*/
's' => '', // string Passes along the query string variable from a search.
'exact' => true, // bool Flag to make it only match whole titles/posts. Default value is false.
'sentence' => true, // bool Flag to make it do a phrase search. Default value is false.
/**
* Post Field Parameters.
*
* @see http://codex.wordpress.org/Class_Reference/WP_Query#Return_Fields_Parameter
*/
'fields' => 'ids' // string Which fields to return. All fields are returned by default.
// Possible values:
// 'ids' - Return an array of post IDs.
// 'id=>parent' - Return an associative array [ parent => ID, … ].
// Passing anything else will return all fields (default) - an array of post objects.
);
?>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment