Up until very recently I had always used get_posts() along with an $args array in order to retrieve new posts or custom posts on a page. However, in the last few weeks I have discovered the awesome power of the WP_Query object and instantly fell in love with how easy it was to use. This article goes over how to use the WP_Query object in your own code.

First things first, let’s take a look at all the options we have for displaying different posts on a page where you’re bringing them in (ie. you are accessing posts you wouldn’t normally get within the loop). You can see a breakdown of the different options available to use by WordPress StackExchange user Rarst listed out below:

• query_posts() is overly simplistic and problematic way to modify 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 pre_get_posts hook, for this purpose. TL;DR don’t use query_posts() ever;
• get_posts() is very similar in usage and accepts same arguments (with some nuances, like different defaults), but returns array of posts, doesn’t modify global variables and is safe to use anywhere;
• WP_Query class powers both behind the scenes, but you can also create and work with your own object of it. Bit more complex, less restrictions, also safe to use anywhere.

Rarst also included this amazing flow chart showing the different options available to you and how they sort of work:

Despite the fact that Rarst claims that WP_Query is a “bit more complex”, I actually think it’s just as easy to use as get_posts(), especially if you’ve done some theme development before. Using WP_Query also lets you use the exact same format as the regular loop from within the loop so your end code ends up being extremely readable and understandable as far as I’m concerned.

To illustrate this let’s take a look at an example piece of code:

Just to go over this example a little:

First we use WP_Query to grab a custom post type – in this case the example custom post type are products that I’ve created. If you want to see more on how to create custom post types please read my WordPress Custom Post Types and WordPress Custom Post Types II articles. For this example I’m pretending that I want to get the featured products and display them – which is a very real world scenario. To do this we add the ‘cat’ => 8 to our array, signifying we want to only get that particular category.  To read more about what you can do with WP_Query searches check out the Codex page for WP_Query. Now that we have the WP_Query object all we have to do is iterate over it.

As you can see from the example above, you essentially create another instance of the loop with your WP_Query object and then treat it exactly like the loop. The only real additional code is a check using have_posts() just to make sure there is something to iterate over, but other than that the code is the exact same as the loop.

So next time you’re looking to add some posts or custom posts to a page, try out WP_Query. You’ll find that it’s extremely powerful, easy to use and safe to use anywhere.

As always thank you for reading and please share it around as much as you can! Please feel free to put any suggestions or ideas for future tutorials in the comments section below.