query_posts()WP 1.5.0

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

#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 »' );
}
?>
1

#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.

0

#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" );
}
0

#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.

0

#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().

-1

#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() code WP 6.6.2

function query_posts( $query ) {
	$GLOBALS['wp_query'] = new WP_Query();
	return $GLOBALS['wp_query']->query( $query );
}