query_posts()
Sets up The Loop with query parameters.
Note: This function will completely override the main query and isn't intended for use by plugins or themes. Its overly-simplistic approach to modifying the main query can be problematic and should be avoided wherever possible. In most cases, there are better, more performant options for modifying the main query such as via the pre_get_posts action within WP_Query.
This must not be used within the WordPress Loop.
No Hooks.
Return
WP_Post[]|Int[]
. Array of post objects or post IDs.
Usage
query_posts( $query );
- $query(array|string) (required)
- Array or string of WP_Query arguments.
Examples
#1 Get only the first part of the content $more = 0
If you want to use the "read more" function with a new query, you must switch the global variable $more
to 0
:
<?php // retrieve one post with an ID of 5 query_posts('p=5'); global $more; // set $more to 0 in order to only get the first part of the post $more = 0; // the Loop while ( have_posts() ) { the_post(); // the content of the post the_content( 'Read the full post »' ); } ?>
#2 Passing parameters in an array
Parameters can also be passed as an array. This makes them clearer and more readable.
query_posts( [ 'cat' => 22, 'year' => $current_year, 'monthnum' => $current_month, 'order' => 'ASC', ] );
As you can see, you can put each variable on a separate line here, and this is clearer and more readable.
#3 Exclude the posts from category 3, On the home page.
It's better to use pre_get_posts hook for this purpose.
To exclude posts that are in category 3 on the home page of your blog, you need to insert the following code in the front-page.php
or home.php
template files before you start the WordPress Loop:
Override the main query with all posts in a specific category:
if ( is_home() ) { query_posts( 'cat=-3' ); }
You can add more categories to the exclusion:
if ( is_home() ) { query_posts( "cat=-1,-2,-3" ); }
#4 Passing variables into query parameters
You can create dynamic query parameters, if you want the query to change depending on the circumstances, write the value of the parameter to a variable and then pass the variable to the query parameters, you can do this in several ways:
1) Assembling a query using single quotes ' '
:
<?php $category_var = $cat; // set the $category_var variable to the ID of the current category $query = 'cat=' . $category_var . '&orderby=date&order=ASC'; // assemble the query query_posts( $query ); // run a query to the database ?>
2) Assembling a query using double quotes ""
Variables inside double quotes are interpreted by PHP as variables, not plain text:
<?php $current_month = date('m'); $current_year = date('Y'); query_posts( "cat=22&year=$current_year&monthnum=$current_month&order=ASC" ); ?> <!--here comes the WordPress Cycle -->
3) Using the global variable $query_string
Which contains the basic query for the query_posts() function. If we want to keep the standard output of WordPress posts (e.g. on a category page) but remove pagination (display all posts on one page), we can add the posts_per_page=-1
parameter to the basic query_posts function:
<?php global $wp_query; $wp_query = new WP_Query( $query_string . '&posts_per_page=-1' ); while( have_posts() ){ the_post(); // here comes the WordPress Cycle } wp_reset_query(); // reset global $wp_query ?>
We can measure the value of posts_per_page
by the specific (int) posts we need on one page. For example, posts_per_page=10
will display only 10 posts, but if you put a template tag posts_nav_link() at the end of the loop, a link to go to the next 10 posts (pagination link) will appear below the loop.
4) Adding parameters to the query
Saving the basic query of the current page and adding your own parameters to it.
the query_posts() function completely rewrites the query, if for example we write query_posts ('cat=1')
, other query parameters that are used for the current page (like sorting, pagination, etc.) will be lost and category 1 posts will be displayed with the other DEFAULT parameters.
To keep the basic query parameters and supplement/replace them with your own, use the PHP function array_merge() (merges 2 arrays into one):
global $wp_query; query_posts( array_merge( ['cat' => 1 ], // this is the parameter we added $wp_query->query // this is an array of basic query of the current page ) );
This example is essentially the same as the one using the global variable $query_string
, only as an array.
#5 Change posts_per_page parameter for specific category
The “Blog pages show at most” parameter in Settings > Reading
can influence your results. To overcome this, add the posts_per_page
parameter. For example:
// if this request is for 'category-slug' category change number of posts if ( is_category( 'category-slug' ) ) { query_posts( [ 'posts_per_page' => 999 ] ); }
Use this code in the category.php
template file.
See is_category().
#6 Get a specific post/page by ID or slug
It's not recommended to use query_posts() for this purpose, use get_posts() or get_post() instead.
Get a single post (with ID = 5):
<?php // retrieve one post with an ID of 5 query_posts('p=5'); ?>
Get a single page with ID 7:
<?php query_posts( 'page_id=7' ); ?>
Get a single page by it's slug:
<?php query_posts( 'pagename=about-site' ); ?>
Retrieving a child page.
For child pages, you must specify the name of the parent page and the child page itself. The names are separated by a slash (/
). Example:
<?php query_posts( 'pagename=about-site/authors' ); // get the "authors" page, which is a child of "about-site" ?>
Notes
- Global. WP_Query. $wp_query WordPress Query object.
Changelog
Since 1.5.0 | Introduced. |
query_posts() query posts code WP 6.6.2
function query_posts( $query ) { $GLOBALS['wp_query'] = new WP_Query(); return $GLOBALS['wp_query']->query( $query ); }