In this post, I am going to tell you everything about the WP_Query class. Not only will I show you how it works with examples, but we will also go through its code and its life cycle.
The goal is that by the end of the post, you will have a deeper, more technical understanding of WP_Query.
As I mentioned, this article is somewhat technical, so take your time to read it. Don’t be in a hurry.
Without further delay, let’s begin!
Basic knowledge: Before you start working with WP_Query
Before you continue reading, I advise you to stop for a moment to read this section, because throughout the post you will find certain technicalities and concepts of an intermediate level.
In order for you to understand the entire post, you need to have some prior knowledge that I list below:
- Understand the basic concepts of PHP: You should be familiar with terms such as class, methods, and attributes… since you will find all this terminology throughout the post. You don’t need to be an expert programmer, but you do need to have the basics laid out.
- Have intermediate knowledge about WordPress: To better understand this article, it is advisable that you are already familiar with the structure of WordPress and that, when talking about the term post, not only does a blog entry come to mind, but also know that a post is also a data type that WordPress uses internally
- Know the essentials about MySQL: As the topic that we are going to deal with throughout this article is closely linked to database access, it is advisable that you have basic knowledge about it.
What is WP_Query?
WP_Query is one of the most important classes defined in WordPress core. It is used to facilitate access to our database.
This class not only makes it easy for us to perform our queries, but it also provides a safe and simple way to do it.
Security
One of the important points that WP_Query makes has to do with security. Let’s say that it “sanitizes” the data it receives, as well as doing different checks to validate the types of data received through different methods.
These actions allow queries to be given a level of security and prevent problems such as SQL injection, which is one of the most common attacks.
While internal data checking and “sanitizing” are a must whenever we work with our database, I highly recommend that you follow a WordPress security guide to protect your website from other potential vulnerabilities.
Simplicity
WP_Query significantly simplifies the work when making our queries against the database.
If you have ever made a slightly difficult SQL query, you will have experienced firsthand how complicated and cumbersome it can be. Especially, if we talk about the use of the JOIN statement.
Thanks to the use of WP_Query we forget about all these problems and we only use a matrix or array that we will pass as a parameter, where we will indicate the actions to be carried out in a much simpler and more readable way.
The WP_Query Lifecycle
Although you don’t need to know what the WP_Query lifecycle is like to be able to use it, I think it’s interesting to tell you how this class works internally. This will allow you to have a deeper knowledge and better understand its operation and, therefore, will also make it easier for you to use.
In this section, I am going to talk to you about some advanced terms such as objects, classes, methods or instances. I am aware that these explanations can become somewhat heavy. Therefore, if you find it difficult to understand, do not worry, you can skip this point.
WP_Query initialization
The first step of all would be to initialize the object. We perform this action when we create a new instance.
When initializing it, its query method will be used, which, in turn, will call a series of methods, among which is the main one, called init.
This function will start its life cycle. This method will call init_query_flags, which will set the flags used in the construction of the query to false.
Extracting the arguments
In this step, the arguments that we have passed as parameters are extracted. The best-known way is through an array, although it also accepts the arguments in URL format.
If we pass our arguments in string or URL format, it will convert these to an array via the wp_parse_args function.
In both cases, these arguments will be used to build the query, being stored in the query and query_vars variables that are defined as properties or attributes of the class.
In general, there are not many differences between them. query_vars contains the information stored inquery y alguna extra, como los argumentos por defecto que no hayamos especificado.
Also, I think it is important to comment on detail: the wp_parse_args method is not part of the WP_Query class but is found inside functions.php in the wp-includes folder. In this file, multiple functions are located that are used throughout the WordPress core.
Setting the flags for the query
Once the arguments have been assigned to the properties that I mentioned before, we start a new stage where the values corresponding to the flags that WP_Query has as parameters will be assigned.
This process is done through the parse_query function where not only the properties of the flags are assigned, but it also performs security actions, such as type checks and sanitization.
All these actions are carried out through a long piece of code that basically contains a collection of control structures such as if, else if, and else.
When we talk about flags in programming we refer to variables where the states of our application or software are stored. These variables are usually of type boolean ( true or false ). For example, if we’re looping through a loop we could use a variable named is_loop and, inside the loop, set it to true . Once we get out of it, we can update our flag or variable and set it to false .
Converting the arguments to an SQL statement
After the parse_query method is finished, all the necessary properties have already been established to be able to start building the query, but we still do not have an SQL statement that our database can understand.
It is built into the get_posts method (a method very similar to parse_query ). This function or method contains a large block of code with conditional statements that will build our query.
Exactly, it has just over 1500 lines of code, in which the get_post method collects other important classes such as WP_Meta_Query, WP_Date_Query, and WP_Tax_Query, all of them belonging to the internal code of WordPress.
In addition to the use of different classes, it also defines two hooks that we can use: pre_get_posts and posts_selection. Of these two hooks, pre_get_posts allow us to perform some very interesting actions when working with the query.
In contrast, the posts_selection hook does not have much “practical” functionality and is intended to be worked on for caching purposes.
Generating WP_Post objects
The last process in the WP_Query lifecycle is converting the returned results to WP_Post objects.
This conversion happens when the get_posts method is called. Once the results have been converted to WP_Post objects, we can access them with the posts variable contained in the WP_Query class.
If we look in the file, we can see that the conversion occurs exactly on this line:
This line makes use of one of the many methods that PHP provides us with for handling arrays. Specifically, it makes use of array_map.
Once the execution of array_map is finished, the value of the posts property is assigned and we will be ready to work with them.
How does WP_Query work?
In this section, I am going to talk about how WP_Query works and how it works through The Loop.
«The Loop» en WordPress
To better understand the use of WP_Query I could give you multiple examples of how to get entries, but the purpose of this article is for you to have a deep understanding of the WP_Query class, and, for that, I have to talk to you about “The Loop”.
Basically, “The Loop” is a piece of code used by WordPress to process and display posts.
Before the WP_Query class was introduced, WordPress ran a query on the wp-blog-header.php file.
The “Loop” was nothing more than an iteration for each that saved the results in the global posts variable. Back then, you couldn’t re-execute the query and it just ran on page load.
With the arrival of the WP_Query class, the methodology changed, saving the results as properties of the said class and allowing the creation of different loops and executions.
The loop and WP_Query
Now that you know a bit about the history of the WordPress loop, I’m going to tell you how the WP_Query class interacts with the loop.
Broadly speaking, the interaction between WP_Query and the loop comes down to the use of a series of internal variables that it manages as they are executed by the loop.
The variables that it manages internally are 4 and, below, I will explain a little about each one:
- current_post: Stores the index value of the current post in the posts array.
- in_the_loop: It consists of a flag or flag that indicates if it is inside the loop or not.
- post: It is a WP_Post object corresponding to the current_post index.
- post_count: Tracks the total number of posts in the posts array.
Checking that there are posts in the loop
WP_Query does a check before executing the loop. This check is done through the have_posts method, which will return true or false depending on whether there are post records or not.
To make sure that there are posts, the have_posts method performs a comparison of the current_post and post_count properties that we saw in the previous point.
After the loop completes, have_posts calls the rewind_posts method, which resets the index of current_post to -1 and changes other internal variables that handle the loop.
Iterating over posts
As I was telling you, in the past “The loop” consisted of a simple for each, but this was replaced by the_post method.
Each time this method is called, the in_the_loop flag will be set to true. After checking that current_post has a value of -1, it will call loop_start, which will start the loop.
It will start calling the next_post method which will increment the index by one, getting the current post and returning its data so you can work with its content.
How to use WP_Query?
Up to this point, we have focused on learning the inner workings of WP_Query: its life cycle, some properties, methods… Now we are going to get our hands dirty and see how to use it through examples.
Keep in mind that executing queries in WordPress will have an impact on the performance of your website, so it is important to work them correctly.
You can check the performance through the Query Monitor plugin and check the load time or the number of queries that your WordPress is executing.
Creating a basic loop with WP_Query
Through the following example, I will break down what you need to know to build a loop with WP_Query.
I’m going to cover the most important points you need to build your queries and customize your content.
I recommend that you do not deploy any code directly to your production hosting and instead do so on a server that you have dedicated for testing or development. If you don’t have any, you can take a look at our WordPress hosting that is specifically designed to work with this CMS.
$args: matrix or array where we will define the data that interests us to build our query. WP_Query supports a large number of values to set in our array. I will briefly indicate some of the most used:
- author (int | string): The id of the author or list of authors separated by commas. It is possible to exclude some specific id using the “-” character.
1’author’ => ‘1,2,3,’ - author_name (string): Uses the ‘user_nicename’ field. It is important not to confuse it with the name field.
1’author_name’ => ‘rail networks’, - cat (int): Will display the posts associated with the indicated category, as well as its child categories, all using the category id.
1’cat’ => 5, - tag (string): Uses the category tag to display the associated post.
1’tag’ => ‘tutorial’, - tax_query (array): matriz o array utilizado para construir consultas complejas. Podemos indicar relaciones con otras tablas, operaciones, exclusiones… Quizás sea el argumento más complejo de manejar.
12345678910
- post_type (string/array): Allows to return the post by its type. By default, its value is ‘post’. It can be used to return CPT or Custom Post Type.
These are some of the values that can be set in args, but there are many others that I have not mentioned, so you can get an idea of the flexibility and ease with which we can build queries.
If you’re interested, I’ve provided a full list of WP_Query arguments that you can use when defining your array to build whatever query you want.
I also want to mention that there are several arguments with default values and, therefore, if they are not specified in our array, those values will be taken. These arguments are as follows:
- posts_per_page: This value is stored in the database in the option ‘posts_per_page’.
- post_type: By default, it will take the value ‘post’.
- post_status: By default, it will take the value ‘publish’.
Initialization: As you already know, the instance of a WP_Query object is done with the following line:
There is not much to explain about this. It simply creates a new object where we will pass the arguments by parameter and it will build the query based on them.
have_posts() method: As I mentioned before, this method simply takes care of checking that we have results that we can loop through.
while loop: It will loop through all the results until the last one as long as there are results. By calling the_post() method we can have the methods of a Post such as the_title() or the_content(), among others.
Resetting the data: If we are using WP_Query within a template or page we should reset the data since WordPress uses the $post variable globally. This variable contains the data for the current post, but using WP_Query and calling the_post method overrides it.
To perform the reset we only have to use the wp_reset_postdata() method. This way we make sure that, if we later use our own methods on the global variable $post, it returns the data of the current $post and not the value assigned by WP_Query.
There is also a similar function called wp_reset_query(). It does almost the same thing. The difference is that we should use the latter if modifications have been made with query_posts().
WP_Query Usage Examples
I am going to show you some examples of WP_Query that can help you better understand its use and that cover different queries. We will see different values that we can set in our argument array and that will provide us with different queries based on them.
We will also see some examples of how to work with our custom posts and not just the default posts.
I want to comment that, inside the while loop, you can work with HTML tags to build the structures that you think are convenient. However, in these examples, I am going to focus on how to perform different queries and not so much on the visual part, which could vary depending on the themes you use in your WordPress installations.
1 – Get the latest posts in a category excluding the current post
It is common to want to show the latest posts of an entry related by the category to which it belongs but, as is logical, we should also exclude the current entry, since it is possible that it has been published recently and we do not want it to appear.
In this example, we will display a link to the post whose text will be the title, and, right after, we will display the main image assigned to the post.
In this post, I am going to tell you everything about the WP_Query class. Not only will I show you how it works with examples, but we will also go through its code and its life cycle.
The goal is that by the end of the post, you will have a deeper, more technical understanding of WP_Query.
As I mentioned, this article is somewhat technical, so take your time to read it. Don’t be in a hurry.
Without further delay, let’s begin!
We won’t spam you, we promise! We send our subscribers our content on WordPress, hosting, digital marketing, and programming.EmailBasic information on data protection: Privacy Policy I have read and accept the privacy policy *https://www.google.com/recaptcha/api2/anchor?ar=1&k=6Lc1StoUAAAAAKI1oisF2YzV-7RTJVYac8d9mYBf&co=aHR0cHM6Ly9yYWlvbGFuZXR3b3Jrcy5lczo0NDM.&hl=en-GB&type=v3&v=gZWLhEUEJFxEhoT5hpjn2xHK&size=invisible&badge=bottomright&sa=Form&cb=fwiwjlphercgTO SEND
Basic knowledge: Before you start working with WP_Query
Before you continue reading, I advise you to stop for a moment to read this section, because throughout the post you will find certain technicalities and concepts of an intermediate level.
In order for you to understand the entire post, you need to have some prior knowledge that I list below:
- Understand the basic concepts of PHP: You should be familiar with terms such as class, methods, and attributes… since you will find all this terminology throughout the post. You don’t need to be an expert programmer, but you do need to have the basics laid out.
- Have intermediate knowledge about WordPress: To better understand this article, it is advisable that you are already familiar with the structure of WordPress and that, when talking about the term post, not only does a blog entry come to mind, but also know that a post is also a data type that WordPress uses internally
- Know the essentials about MySQL: As the topic that we are going to deal with throughout this article is closely linked to database access, it is advisable that you have basic knowledge about it.
What is WP_Query?
WP_Query is one of the most important classes defined in WordPress core. It is used to facilitate access to our database.
This class not only makes it easy for us to perform our queries, it also provides a safe and simple way to do it.
Security
One of the important points that WP_Query makes has to do with security. Let’s say that it “sanitizes” the data it receives, as well as doing different checks to validate the types of data received through different methods.
These actions allow queries to be given a level of security and prevent problems such as SQL injection, which is one of the most common attacks.
While internal data checking and “sanitizing” are a must whenever we work with our database, I highly recommend that you follow a WordPress security guide to protect your website from other potential vulnerabilities.
simplicity
WP_Query significantly simplifies the work when making our queries against the database.
If you have ever made a slightly difficult SQL query, you will have experienced firsthand how complicated and cumbersome it can be. Especially, if we talk about the use of the JOIN statement.
Thanks to the use of WP_Query we forget about all these problems and we only use a matrix or array that we will pass as a parameter, where we will indicate the actions to be carried out in a much simpler and more readable way.
The WP_Query Lifecycle
Although you don’t need to know what the WP_Query lifecycle is like to be able to use it, I think it’s interesting to tell you how this class works internally. This will allow you to have a deeper knowledge and better understand its operation and, therefore, will also make it easier for you to use.
In this section, I am going to talk to you about some advanced terms such as objects, classes, methods or instances. I am aware that these explanations can become somewhat heavy. Therefore, if you find it difficult to understand, do not worry, you can skip this point.
WP_Query initialization
The first step of all would be to initialize the object. We perform this action when we create a new instance.
When initializing it, its query method will be used, which, in turn, will call a series of methods, among which is the main one, called init.
This function will start its life cycle. This method will call init_query_flags, which will set the flags used in the construction of the query to false.
Extracting the arguments
In this step, the arguments that we have passed as parameters are extracted. The best-known way is through an array, although it also accepts the arguments in URL format.
If we pass our arguments in string or URL format, it will convert these to an array via the wp_parse_args function.
In both cases, these arguments will be used to build the query, being stored in the query and query_vars variables that are defined as properties or attributes of the class.
In general, there are not many differences between them. query_vars contains the information stored inquery y alguna extra, como los argumentos por defecto que no hayamos especificado.
Also, I think it is important to comment on detail: the wp_parse_args method is not part of the WP_Query class but is found inside functions.php in the wp-includes folder. In this file, multiple functions are located that are used throughout the WordPress core.
Setting the flags for the query
Once the arguments have been assigned to the properties that I mentioned before, we start a new stage where the values corresponding to the flags that WP_Query has as parameters will be assigned.
This process is done through the parse_query function where not only the properties of the flags are assigned, but it also performs security actions, such as type checks and sanitization.
All these actions are carried out through a long piece of code that basically contains a collection of control structures such as if, else if and else.
When we talk about flags in programming we refer to variables where the states of our application or software are stored. These variables are usually of type boolean ( true or false ). For example, if we’re looping through a loop we could use a variable named is_loop and, inside the loop, set it to true . Once we get out of it, we can update our flag or variable and set it to false .
Converting the arguments to an SQL statement
After the parse_query method is finished, all the necessary properties have already been established to be able to start building the query, but we still do not have an SQL statement that our database can understand.
It is built into the get_posts method (a method very similar to parse_query ). This function or method contains a large block of code with conditional statements that will build our query.
Exactly, it has just over 1500 lines of code, in which the get_post method collects other important classes such as WP_Meta_Query, WP_Date_Query, and WP_Tax_Query, all of them belonging to the internal code of WordPress.
In addition to the use of different classes, it also defines two hooks that we can use: pre_get_posts and posts_selection. Of these two hooks, pre_get_posts allow us to perform some very interesting actions when working with the query.
In contrast, the posts_selection hook does not have much “practical” functionality and is intended to be worked on for caching purposes.
Generating WP_Post objects
The last process in the WP_Query lifecycle is converting the returned results to WP_Post objects.
This conversion happens when the get_posts method is called. Once the results have been converted to WP_Post objects, we can access them with the posts variable contained in the WP_Query class.
If we look in the file, we can see that the conversion occurs exactly on this line:
This line makes use of one of the many methods that PHP provides us with for handling arrays. Specifically, it makes use of array_map.
Once the execution of array_map is finished, the value of the posts property is assigned and we will be ready to work with them.
How does WP_Query work?
In this section, I am going to talk about how WP_Query works and how it works through The Loop.
«The Loop» en WordPress
To better understand the use of WP_Query I could give you multiple examples of how to get entries, but the purpose of this article is for you to have a deep understanding of the WP_Query class, and, for that, I have to talk to you about “The Loop”.
Basically, “The Loop” is a piece of code used by WordPress to process and display posts.
Before the WP_Query class was introduced, WordPress ran a query on the wp-blog-header.php file.
The “Loop” was nothing more than an iteration for each that saved the results in the global posts variable. Back then, you couldn’t re-execute the query and it just ran on page load.
With the arrival of the WP_Query class, the methodology changed, saving the results as properties of the said class and allowing the creation of different loops and executions.
The loop and WP_Query
Now that you know a bit about the history of the WordPress loop, I’m going to tell you how the WP_Query class interacts with the loop.
Broadly speaking, the interaction between WP_Query and the loop comes down to the use of a series of internal variables that it manages as they are executed by the loop.
The variables that it manages internally are 4 and, below, I will explain a little about each one:
- current_post: Stores the index value of the current post in the posts array.
- in_the_loop: It consists of a flag or flag that indicates if it is inside the loop or not.
- post: It is a WP_Post object corresponding to the current_post index.
- post_count: Tracks the total number of posts in the posts array.
Checking that there are posts in the loop
WP_Query does a check before executing the loop. This check is done through the have_posts method, which will return true or false depending on whether there are post records or not.
To make sure that there are posts, the have_posts method performs a comparison of the current_post and post_count properties that we saw in the previous point.
After the loop completes, have_posts calls the rewind_posts method, which resets the index of current_post to -1 and changes other internal variables that handle the loop.
Iterating over posts
As I was telling you, in the past “The loop” consisted of a simple for each, but this was replaced by the_post method.
Each time this method is called, the in_the_loop flag will be set to true. After checking that current_post has a value of -1, it will call loop_start, which will start the loop.
It will start calling the next_post method which will increment the index by one, getting the current post and returning its data so you can work with its content.
How to use WP_Query?
Up to this point, we have focused on learning the inner workings of WP_Query: its life cycle, some properties, methods… Now we are going to get our hands dirty and see how to use it through examples.
Keep in mind that executing queries in WordPress will have an impact on the performance of your website, so it is important to work them correctly.
You can check the performance through the Query Monitor plugin and check the load time or the number of queries that your WordPress is executing.
Creating a basic loop with WP_Query
Through the following example, I will break down what you need to know to build a loop with WP_Query.
I’m going to cover the most important points you need to build your queries and customize your content.
I recommend that you do not deploy any code directly to your production hosting and instead do so on a server that you have dedicated for testing or development. If you don’t have any, you can take a look at our WordPress hosting that is specifically designed to work with this CMS.
$args: matrix or array where we will define the data that interests us to build our query. WP_Query supports a large number of values to set in our array. I will briefly indicate some of the most used:
- author (int | string): The id of the author or list of authors separated by commas. It is possible to exclude some specific id using the “-” character.
1’author’ => ‘1,2,3,’ - author_name (string): Uses the ‘user_nicename’ field. It is important not to confuse it with the name field.
1’author_name’ => ‘rail networks’, - cat (int): Will display the posts associated with the indicated category, as well as its child categories, all using the category id.
1’cat’ => 5, - tag (string): Uses the category tag to display the associated post.
1’tag’ => ‘tutorial’, - tax_query (array): matriz o array utilizado para construir consultas complejas. Podemos indicar relaciones con otras tablas, operaciones, exclusiones… Quizás sea el argumento más complejo de manejar.
12345678910’tax_query’ => array( array( ‘taxonomy’ => ‘my-taxonomy’, ‘terms’ => array( ’11’, ’12’ ), ‘operator’ => ‘NOT IN’ )) - post_type (string / array): Allows to return the post by its type. By default, its value is ‘post’. It can be used to return CPT or Custom Post Type.
These are some of the values that can be set in args, but there are many others that I have not mentioned, so you can get an idea of the flexibility and ease with which we can build queries.
If you’re interested, I’ve provided a full list of WP_Query arguments that you can use when defining your array to build whatever query you want.
I also want to mention that there are several arguments with default values and, therefore, if they are not specified in our array, those values will be taken. These arguments are as follows:
- posts_per_page: This value is stored in the database in the option ‘posts_per_page’.
- post_type: By default, it will take the value ‘post’.
- post_status: By default, it will take the value ‘publish’.
Initialization: As you already know, the instance of a WP_Query object is done with the following line:
There is not much to explain about this. It simply creates a new object where we will pass the arguments by parameter and it will build the query based on them.
have_posts() method: As I mentioned before, this method simply takes care of checking that we have results that we can loop through.
while loop: It will loop through all the results until the last one as long as there are results. By calling the_post() method we can have the methods of a Post such as the_title() or the_content(), among others.
Resetting the data: If we are using WP_Query within a template or page we should reset the data since WordPress uses the $post variable globally. This variable contains the data for the current post, but using WP_Query and calling the_post method overrides it.
To perform the reset we only have to use the wp_reset_postdata() method. This way we make sure that, if we later use our own methods on the global variable $post, it returns the data of the current $post and not the value assigned by WP_Query.
There is also a similar function called wp_reset_query(). It does almost the same thing. The difference is that we should use the latter if modifications have been made with query_posts().
WP_Query Usage Examples
I am going to show you some examples of WP_Query that can help you better understand its use and that cover different queries. We will see different values that we can set in our argument array and that will provide us with different queries based on them.
We will also see some examples of how to work with our custom posts and not just the default posts.
I want to comment that, inside the while loop, you can work with HTML tags to build the structures that you think are convenient. However, in these examples, I am going to focus on how to perform different queries and not so much on the visual part, which could vary depending on the themes you use in your WordPress installations.
1 – Get the latest posts in a category excluding the current post
It is common to want to show the latest posts of an entry related by the category to which it belongs but, as is logical, we should also exclude the current entry, since it is possible that it has been published recently and we do not want it to appear.
In this example, we will display a link to the post whose text will be the title, and, right after, we will display the main image assigned to the post.
2 – Mostrar los CPT de un author en concreto
In this example, we will get our Custom Post Types or CPT from a specific author. We get the author bypassing his id in author as a parameter. For this example, we simply pass it that we want the author’s CPTs with ID 1.
I must clarify that, of course, the author‘s id could be passed to it dynamically, but for this example, I have decided to pass it a specific ID directly so you can see how it works. In this way, in the array of arguments, we would directly assign the author’s id.
I also want to mention that our CPT should support authors.
In addition, we are going to order it in descending order according to its date and obtain 10 results per page.
3 – Show products with a specific tag
As you have seen before, WP_Query can work with CPT without any problem or, what is the same, we can work with our custom posts.
In this example, we are going to work with the products of your online store set up in WordPress.
With this code, we will obtain the products that have a specific tag assigned. We will also tell you through an order by to order our products by their id.
4 – Show custom posts type with a specific value created with ACF
In this example, we will display CPTs that contain a specific value created through ACF.
Let’s assume that we have created a CPT called “projects” and we have assigned a “finished” field to it.
As the custom fields are still custom meta keys, we can quickly obtain the projects whose “finished” field is “yes” through an array of arguments.
It will suffice to indicate in the array that we will pass to generate our query, the key of the meta and the value that we want it to have.
Conclusión
I hope that after reading this article you have a better understanding of what WP_Query is and how to work with it when building your queries on your website.
I also want to congratulate you if you have taken your time to read it, as I am aware that this article is somewhat technical. However, I think it is interesting to delve not only into the functionalities but also into a deeper study. After all, a good understanding of the WordPress core will help you develop better projects with this CMS.
