Advertisement
  1. Code
  2. WordPress
Code

Mastering WP_Query: Properties and Methods

by
Difficulty:IntermediateLength:MediumLanguages:
This post is part of a series called Mastering WP_Query.
Mastering WP_Query: Actions and Filters
WP_Query Arguments: Posts, Pages and Post Types

Welcome to yet another part of our "Mastering WP_Query" series. How are we doing so far? I hope you're enjoying these tutorials as much as we're enjoying writing them.

In this tutorial, you're going to learn about the properties and methods of the WP_Query class. But first, I think it's appropriate to talk about what "properties" and "methods" are in a class.

Shall we?

What Are Properties and Methods, Exactly?

In PHP, there's a way to write code in a cleaner way: object-oriented programming, or OOP. With OOP, we use "classes" as blueprints—I took the term from one of the classic posts of Code Tuts+, "Object-Oriented PHP for Beginners" by Jason Lengstorf:

A class, for example, is like a blueprint for a house. It defines the shape of the house on paper, with relationships between the different parts of the house clearly defined and planned out, even though the house doesn't exist.

(And remember that WP_Query is an essential class of the WordPress core.)

When you understand the notion of PHP classes, "properties" and "methods" become extremely easy to understand since the words are just synonyms for "variables" and "functions". Yep, properties are variables of a PHP class and methods are functions of a PHP class.

Now we've covered what they are, let's get to know each of those properties and methods.

Warning: It wouldn't be wise to change the properties directly. As the Codex says, you should interact with them using the methods of WP_Query.

Properties of the WP_Query Class

Let's begin with the properties, or the variables, of the WP_Query class.

The Query String: $query

This property stores the query passed to the $wp_query object.

The Array of Query Variables: $query_vars

This property stores an associative array of the variables (and their values) of $query.

The Queried Object: $queried_object

This property stores the currently queried object, like the $post object if it's a post query or the $author object if it's an author query.

The ID of the Queried Object: $queried_object_id

This property stores the ID of the queried object.

The Posts Returned From the Query: $posts

This property stores the posts returned from the query.

The Number of Posts Being Displayed: $post_count

This property stores the number of posts for the current query.

The Number of Posts Returned from the Query: $found_posts

This property stores the number of posts without the LIMIT clause of the SQL query.

The Number of Pages: $max_num_pages

This property stores the number of pages—it's calculated by dividing $found_posts by $posts_per_page.

The Index of the Current Post: $current_post

This property stores the index number of the current item in the Loop. For example, it's -1 if the Loop has just started and it's incremented by the next_post() method.

The Current Post: $post

This property stores, well, the current post.

Conditional Tag Booleans: $is_{conditional}

The following properties are stored as booleans, giving information about the current post's status:

  • $is_single: Checks if it's a single post of any post type (except "attachment" and "page" post types) or not.
  • $is_page: Checks if it's a page or not.
  • $is_archive: Checks if it's an archive page or not.
  • $is_preview: Checks if it's a post preview or not.
  • $is_date: Checks if it's a date-based archive page or not.
  • $is_year: Checks if it's a year-based archive page or not.
  • $is_month: Checks if it's a month-based archive page or not.
  • $is_time: Checks if it's a time-based (hourly, minutely or secondly) archive page or not.
  • $is_author: Checks if it's an author's archive page or not.
  • $is_category: Checks if it's a category archive page or not.
  • $is_tag: Checks if it's a tag archive page or not.
  • $is_tax: Checks if it's a taxonomy archive page or not.
  • $is_search: Checks if it's a "search results" page or not.
  • $is_feed: Checks if it's a feed or not.
  • $is_comment_feed: Checks if it's a comment feed or not.
  • $is_trackback: Checks if it's a trackback or not.
  • $is_home: Checks if it's the main blog page or not.
  • $is_404: Checks if it's a 404 error page or not.
  • $is_comments_popup: Checks if it's a comments popup window or not.
  • $is_admin: Checks if it's the administration panel or not.
  • $is_attachment: Checks if it's an attachment or not.
  • $is_singular: Checks if it's a single post of any post type (including "attachment" and "page" post types) or not.
  • $is_robots: Checks if it's a query for the robots.txt file or not.
  • $is_posts_page: Checks if it's the "Posts Page" (set on the "Reading Settings" page in the admin panel) or not.
  • $is_paged: Checks if it's a paginated query and it's not the first page.

Methods of the WP_Query Class

Now that we're done with the properties, let's move on to the methods (functions) of the WP_Query class.

init()

This method simply initializes the object, setting all properties to NULL, 0 or FALSE.

parse_query( $query )

This method uses the $query property to parse the query and populate all other properties (except $posts, $post_count, $post and $current_post).

parse_query_vars()

This method reparses the query variables.

get( $query_var )

This method fetches a given query variable.

set( $query_var, $value )

This method sets the given query variable to a specific value.

&get_posts()

This method returns the posts requested by the query and populates the $posts and $post_count properties.

next_post()

This method increments the $current_post index and advances to the next post in $posts, returning the current post object. (This method must be used inside a Loop to work properly.)

the_post()

This method sets the global $post variable with the next post's data. (This method must be used inside a Loop to work properly.)

have_posts()

This method checks if there are any posts left to work on, and returns FALSE if there aren't. (This method must be used before a Loop to work properly.)

rewind_posts()

This method simply resets the $current_post and $post properties.

&query( $query )

This method calls two of its sibling methods, parse_query() and get_posts(), and returns the result of get_posts().

get_queried_object()

This method returns the queried object. (It sets $queried_object if it's not already set.)

get_queried_object_id()

This method, similar to the one above, returns the queried object's ID ($queried_object_id).

Quick Tip: If there's an ampersand before a method, it means that the method returns by reference.

Wrapping Up for Today

I hope I managed to make it clear for you what "properties" and "methods" mean for classes. And if you understood the purpose of the properties and methods of the WP_Query class, I can say that I've done a decent job!

Do you have anything to add to this article? Share your thoughts with us in the Comments section below. And if you liked the article, don't forget to share it with your friends.

See you in the next part of the series!

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.