Wordpress - When should you use WP_Query vs query_posts() vs get_posts()?
query_posts()
is overly simplistic and a problematic way to modify the main query of a page by replacing it with new instance of the query. It is inefficient (re-runs SQL queries) and will outright fail in some circumstances (especially often when dealing with posts pagination). Any modern WP code should use more reliable methods, like making use of thepre_get_posts
hook, for this purpose. TL;DR don't use query_posts() ever.get_posts()
is very similar in usage and accepts the same arguments (with some nuances, like different defaults), but returns an array of posts, doesn't modify global variables and is safe to use anywhere.WP_Query
is the class that powers both behind the scenes, but you can also create and work with your own instance of it. A bit more complex, fewer restrictions, also safe to use anywhere.
query_posts
- You should never ever use query_posts
. Apart from what @Rarst has said, the really big issue with query_posts
is, it breaks the main query object ( stored in $wp_query
). A lot of plugins and custom code relies on the main query object, so breaking the main query object means that you are breaking the functionalities of plugins and custom code. Just one such function is the all important pagination function, so if you break the main query, you break pagination.
To prove how bad query_posts
is, on any template, do the following and compare the results
var_dump( $wp_query );
query_posts( '&posts_per_page=-1' );
var_dump( $wp_query );
get_posts
and WP_Query
are the correct way to construct secondary queries ( like related posts, sliders, featured content and content on static front pages ) with. It should be noted, you should not use any of the two in favor of the main query on the home page, single page or any type of archive page as it will break page functionality. If you need to modify the main query, use pre_get_posts
to do so, and not a custom query. (UPDATE: For static front pages and true pages, see Using pre_get_posts on true pages and static front pages*)
In essence, WP_Query
is used by the main query and is also used by get_posts
, but although get_posts()
uses WP_Query
, there are a few differences
get_posts
are faster thanWP_Query
. The margin depends on the amount of total posts of the site. The reason for this is,get_posts
passes'no_found_rows' => true
by default toWP_Query
which skips/legally breaks pagination. With'no_found_rows' => true
,WP_Query
gets the amount of posts queried, then bails out, where by default, it further search for all posts matching the query in order to calculate pagination.For this reason,
get_posts()
should be used for non paginated queries only. Paginatingget_posts
is really one big mess.WP_Query
should be used for all paginated queriesget_posts()
aren't influenced by theposts_*
filters whereWP_Query
gets influenced by these filters. The reason is thatget_posts
, by default, passes'suppress_filters' => true
toWP_Query
get_posts
has a couple of extra parameters likeinclude
,exclude
,numberposts
andcategory
. These parameters do get changed into valid parameters forWP_Query
before being passed toWP_Query
.include
gets changed intopost__in
,exclude
intopost__not_in
,category
intocat
andnumberposts
intoposts_per_page
. Just a note, all of the parameters that can be passed toWP_Query
works withget_posts
, you can ignore and not use the default parameters ofget_posts
get_posts
returns just the$posts
property ofWP_Query
whileWP_Query
returns the complete object. This object is quite useful when it comes to conditionals, pagination and other useful info that can be used inside the loop.get_posts
doesn't use the loop, but aforeach
loop to display posts. Also, no template tags are available by default.setup_postdata( $post )
has to be used to make the template tags available.WP_Query
uses the loop and template tags are available by defaultget_posts
passes'ignore_sticky_posts' => 1
toWP_Query
, soget_posts
by default ignores sticky posts
Based on the above, whether to use get_posts
or WP_Query
is up to you and what do you actually need from the query. The above should guide you in your choice
The basic difference is that query_posts()
is really only for modifying the current Loop. Once you're done it's necessary to reset the loop and send it on its merry way. This method is also a little easier to understand, simply because your "query" is basically a URL string that you pass to the function, like so:
query_posts('meta_key=color&meta_value=blue');
On the other hand, WP_Query
is more of a general purpose tool, and is more like directly writing MySQL queries than query_posts()
is. You can also use it anywhere (not just in the Loop) and it doesn't interfere with any currently running post queries.
I tend to use WP_Query
more often, as it happens. Really, it's going to come down to your specific case.