WP_Query Arguments: Date

In this series on WP_Query, you've been learning how to use the WP_Query class to create custom queries in your theme files or plugins.

This part of the series will take you through the arguments you can use to create both simple and complex date queries, to output posts published on, before, after or between given dates.

I'll show you what parameters are available to you and how to use them to write your queries. But first, a reminder of how arguments work in WP_Query.

A Recap on How Arguments Work in WP_Query

Before we start, let's have a quick 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.

Date Parameters

You can also use parameters to query for posts with a publish date on a given date. You can be as specific as you like with dates, using years and months for example to retrieve a number of posts.

You can write a simple set of arguments or you can use date_query to create nested arrays and run more complex queries. Let's start with the simpler arguments.

Simple Date Arguments

The parameters you can use to query by date are:

year (int): Four-digit year (e.g. 2015).
monthnum (int): Month number (from 1 to 12).
w (int): Week of the year (from 0 to 53). The mode is dependent on the "start_of_week" option which you can edit in your Settings page in the admin.
day (int): Day of the month (from 1 to 31).
hour (int): Hour (from 0 to 23).
minute (int): Minute (from 0 to 60).
second (int): Second (0 to 60).
m (int): YearMonth (e.g. 201502).

So imagine you're running an events site that uses the publish date for each event to denote the event start date. To want to display all events, past and future, happening in 2015, here are the arguments you'd need:

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'year' => '2015'
);

Note that I've used future and publish for the post status, as posts scheduled for a future date aren't queried by default.

Or if you wanted to automatically display events happening this year, and not update your query every year, you could first get the current year and then pass that in your query arguments:

$current_year = the_date( 'Y' );

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'year' => $current_year
);

Complex Date Arguments

To use multiple date parameters to create more complex queries, you use the date_query parameter. This gives you access to more parameters:

year (int): Four-digit year (e.g. 2015).
month (int): Month number (from 1 to 12).
week (int): Week of the year (from 0 to 53).
day (int): Day of the month (from 1 to 31).
hour (int): Hour (from 0 to 23).
minute (int): Minute (from 0 to 59).
second (int): Second (0 to 59).
after (string/array): Date to retrieve posts after.
before (string/array): Date to retrieve posts before.
inclusive (boolean): For after/before, whether exact value should be matched or not.
compare (string): An operator you use to compare data in the database to your arguments. Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS', and 'NOT EXISTS'.
column (string): Database column to query against: the default is 'post_date'.
relation (string): OR or AND, how the sub-arrays should be compared. The default is AND.

The date_query parameter is formatted like this:

$args = array(
    'date_query' => array(
        array(
            // Arguments go here.        
        )
    )
);

You can also create multiple arrays and define how they will be compared using the relation parameter. The below example will return queries that match the arguments in both arrays:

$args = array(
    'date_query' => array(
        'relation' => 'AND',
        array(
            // Arguments go here.
        ),
        array(
            // Arguments go here.
        )
    )
);

While the code below will fetch posts that match the arguments in either array (or both):

$args = array(
    'date_query' => array(
        'relation' => 'OR',
        array(
            // Arguments go here.
        ),
        array(
            // Arguments go here.
        )
    )
);

Let's illustrate this with an example. Let's say you're working on a college website and want to display posts from this academic year. The academic year runs from 1 September 2014 to 31 August 2015, so you'd need to find posts in the relevant months and years:

$args = array(
    'date_query' => array(
        'relation' => 'OR',
        array(
            'year' => '2014',
            'month' => ( '9, 10, 11, 12' )
        ),
        array(
            'year' => '2015',
            'month' => ( '1, 2, 3, 4, 5, 6, 7, 8' )
        )
    )
);

Note that the month parameter takes a string for its arguments, not an array.

The before and after Parameters

An alternative to the example above is to define the dates before and/or after which you want to display posts, using the before and after parameters. These take three arguments:

year (string): Accepts any four-digit year: empty by default.
month (string): The month of the year (1 to 12). The default is 12.
day (string): The day of the month (1 to 31). The default is the last day of the month.

You can also use a string for the date, as long as it's compatible with the php strtotime format.

So returning to my example of displaying posts for this academic year, I have two more options. Firstly, I could use a nested array with the year and month parameters:

$args = array(
    'date_query' => array(
        'relation' => 'AND',
        array(
            'after' => array(
                'year' => '2014',
                'month' => '9'
            ),
            'inclusive' => true
        ),
        array(
            'before' => array(
                'year' => '2015',
                'month' => '8'
            ),
            'inclusive' => true
        )
    )
);

There are a couple of things to note here:

I've used 'relation' => 'AND' because the posts need to have been published after my start date and before my end date.
For each of the nested arrays, I've used 'inclusive' => true to ensure that WordPress fetches posts published during September 2014 and August 2015.

I could also write this query using a string for the dates:

$args = array(
    'date_query' => array(
        array(
            'after' => 'August 31st, 2014',
            'before' => 'September 1st, 2015',
            'inclusive' => false,
        )
    )
);

Note that because of the way date strings work, it's more reliable to use exclusive dates. This is because if you use a date string, this will be converted to 00:00 on that date. So to make it work, either use the time in your string as well, or do as I've done and use the day before the date you want to show posts from (and after the date you want to show posts until).

Something else you can do with date parameters is display posts published today. Going back to my events site, let's say I want to display a big banner on my home page on the day when an event is happening. I can write a query for this and then output details of the event if one is found. Here are the arguments:

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'date_query' => array(
        array(
            'year' => date( 'Y' ),
            'month' => date( 'M' ),
            'day' => date( 'D' )
        )
    )
);

Using the date() function returns the current date—I've used this three times to ensure I get the correct day, month and year. Note that I've also included the post_status argument to ensure that an event happening later today is included.

Summary

Sometimes you don't just want to query all the published posts. By using the WP_Query class you can create much more specific queries to output posts by date, including the posts you published on a given date, before a date, after a date or between a pair of dates.

The date_query arguments combine with other parameters such as post_status, which is covered in more detail elsewhere in this series.

HIGHLIGHTS OF THE DAY