So far in this series you've learned about a selection of arguments you can use with the WP_Query class, to select posts by post type, category, tag, metadata, date, status and much more.

In this final tutorial on WP_Query arguments, I'll run through some less frequently used parameters which can give your queries even more flexibility.

The parameters we'll cover here are for:

• author
• search
• password
• permissions
• caching
• return fields

Before we start, let's a have a quick recap on how you code your arguments with WP_Query.

A Recap on How Arguments Work in WP_Query

When you code WP_Query in your themes or plugins, you need to include four main elements:

• the arguments for the query, using parameters which will be covered in this tutorial
• the query itself
• the loop
• finishing off: closing if and while tags and resetting post data

In practice this will look something like the following:

<?php

$args = array(
    // Arguments for your query.
);

// Custom query.
$query = new WP_Query( $args );

// Check that we have query results.
if ( $query->have_posts() ) {

    // Start looping over the query results.
    while ( $query->have_posts() ) {

        $query->the_post();

        // Contents of the queried post results go here.

    }

}

// Restore original post data.
wp_reset_postdata();

?>

The arguments are what tells WordPress what data to fetch from the database and it's those that I'll cover here. So all we're focusing on here is the first part of the code:

$args = array(
    // Arguments for your query.
);

As you can see, the arguments are contained in an array. You'll learn how to code them as you work through this tutorial.

Coding Your Arguments

There is a specific way to code the arguments in the array, which is as follows:

$args = array(
    'parameter1' => 'value',
    'parameter2' => 'value',
    'parameter3' => 'value'
);

You must enclose the parameters and their values in single quotation marks, use => between them, and separate them with a comma. If you get this wrong, WordPress may not add all of your arguments to the query or you may get a white screen.

Author Parameters

There are four parameters you can use for querying by author:

• author (int): use author ID
• author_name (string): use 'user_nicename' (NOT name)
• author__in (array): use author ID
• author__not_in (array)

The first one, author, lets you query posts by one or more authors, by supplying the author's ID:

$args = array(
    'author' => '2'
);

The code above queries all posts by the author whose ID is 2.

You could also use a string to query posts by more than one author:

$args = array(
    'author' => '1, 2'
);

If you wanted to query by name, you would use the author_name parameter:

$args = array(
    'author_name' => 'rachelmccollin'
);

This parameter takes the value from the user_nicename field in the database as its argument, which is displayed as the nickname in the Users admin screen:

Note that as this is editable by users, you'll be safer to use the author parameter if you think your users might change it.

You can also query for posts by an array of authors:

$args = array(
    'author__in' => array(
        '1',
        '2'
    )
);

The above will query for posts by two authors: those with ID 1 and 2, giving you the same results as the string I used with the author parameter above.

Finally, you can exclude posts by one or more authors using the author__not_in parameter. The argument below queries for all posts except those by author 1:

$args = array(
    'author__not_in' => array( '1' )
);

Or you can exclude multiple authors:

$args = array(
    'author__not_in' => array(
        '1',
        '2'
    )
);

Alternatively you can use the author parameter and use a minus sign in front of the author ID to exclude an author:

$args = array(
    'author' => '-2'
);

Search Parameter

There is just one parameter for searching, which is s. Use it to query for posts which match a search term. So for example to query for posts containing the keywords 'my favorite food', you'd use this:

$args = array(
    's' => 'my favorite food'
);

You might find this useful to search for related posts with similar keywords, for example.

Password Parameters

You can use the two password parameters to query posts with and without password protection:

• has_password (bool)
• post_password (string)

The first parameter, has_password, lets you query for posts with or without password protection. So to query for posts which are password-protected:

$args = array(
    'has_password' => true
);

And for posts which don't have passwords:

$args = array(
    'has_password' => false
);

You can also query by the password itself, using the post_password parameter:

$args = array(
    'post_password' => 'mypassword'
);

Permissions Parameter

There is just one parameter available for permissions, perm, which you use to query posts which the current user has permission to read. It takes the 'readable' value and is designed to be combined with other arguments.

So to query password protected posts and display them only if the user has the appropriate permissions, you would use this:

$args = array(
    'has_password' => true,
    'perm' => 'readable'
);

Or to display draft posts if the current user has permission to view them, you'd use this:

$args = array(
    'post_status' => 'draft',
    'perm' => 'readable'
);

Caching Paramaters

There are three caching parameters, which prevent the data retrieved by the query from being added to the cache:

• cache_results (boolean): post information cache
• update_post_meta_cache (boolean): post meta information cache
• update_post_term_cache (boolean): post term information cache

The default value of all three is true: you don't need to use them if you want the data to be added to the cache.

So to display all posts of the product post type but not add post information to the cache, you'd use this:

$args = array(
    'post_type' => 'product',
    'cache_results' => false
);

Normally you shouldn't use these parameters, as it's good practice to add post data to the cache. However you might sometimes want to retrieve posts so that you can just use some of the post data, in which case you don't need the rest of the post data in the cache. An example might be when you just want to output a list of post titles with links, in which case you don't need the post term data or metadata to be added to the cache:

$args = array(
    'post_type' => 'product',
    'update_post_meta_cache' => false,
    'update_post_term_cache' => false
);

Return Fields Parameter

You can use the fields parameter to specify which fields to return from your query. This can save returning data from fields in the database which you don't need when outputting the data in your loop.

The default is to return all fields, but you have two options with the fields parameter to restrict this. First, the 'ids' argument:

$args = array(
    'fields' => 'ids'
);

This would just return an array of post IDs and no other fields. If you wanted to output anything in your loop (such as the post title) you'd then have to use functions such as get_the_title ($post->ID); to output the title, which would be a long-winded way of going about things.

The other argument you can use fetches an associative array of post IDs with child post IDs:

$args = array(
    'fields' => 'id=>parent'
);

You would use this to query for posts according to your other arguments plus their children.

Summary

This part of the series on WP_Query introduces the final set of parameters for the WP_Query class. You can use these to query posts by author, password protected status or the password itself and search terms, and to set whether the results of the query are added to the cache and which fields are returned by the query.

In the next part of this series, you'll see some worked examples of using WP_Query in your themes or plugins.