Functional Docs: WP_Date_Query

[DrewAPicture]

This task was split off from #25367 in an attempt to get the WP_Date_Query functional documentation finished in time for 3.7.

Comments from @Viper007Bond on the original WP_Date_Query inline docs patch here: 3:ticket:25367

First-pass patch attached.

[DrewAPicture]

First pass

[Viper007Bond]

Patch needs updating per my previous comment.

[aeg0125]

Be gentle, this is my first attempt at contributing to core.

[Viper007Bond]

Great!

I think I only have a couple things to be super nitpicky about:

• "filterable via the 'date_query_valid_columns' hook" should probably be "filter" instead of "hook".
• "Include results from months specified in 'before' or 'after'." should probably use "dates" instead of "months".

Otherwise it looks commit worthy to me! :D

[aeg0125]

Additional changes made

[DrewAPicture]

Some remaining notes with 25552.3.diff​:

• There is bound to be confusion between specifying the column to query against in the three separate contexts. As this currently reads, you can specify the column in the first and second-level arrays, as well as the second parameter passed to the constructor. What's the difference between them and does specifying one in one place affect the others?
• The same goes for the compare value in the first and second-level arrays. How are they related or not related?
• Since the structure for these date queries could end up being pretty complex, we'll probably need to be more specific about the interplay between the different arguments. If X is specified, how does it affect Y & Z, etc.?

[Viper007Bond]

Replying to DrewAPicture:

• There is bound to be confusion between specifying the column to query against in the three separate contexts. As this currently reads, you can specify the column in the first and second-level arrays, as well as the second parameter passed to the constructor. What's the difference between them and does specifying one in one place affect the others?

It's inherited if not specified, meaning you can do this:

// Any posts made over a year ago
// but modified in the past month
$some_posts = new WP_Query( array(
    'date_query' => array(
        array(
            'before' => '1 year ago',
        ),
        array(
            'column' => 'post_modified_gmt',
            'after'  => '1 month ago',
        )
    ),
    'posts_per_page' => -1,
) );

[DrewAPicture]

Replying to Viper007Bond:

Replying to DrewAPicture:

• There is bound to be confusion between specifying the column to query against in the three separate contexts. As this currently reads, you can specify the column in the first and second-level arrays, as well as the second parameter passed to the constructor. What's the difference between them and does specifying one in one place affect the others?

It's inherited if not specified, meaning you can do this:

I understand the difference, I'm saying we need to convey that in the docs ;)

[aeg0125]

Thanks for your patience on this. Sorry for the delay, I had to sleep on it to try to work out the logic in my head to try to write it down.

[aeg0125]

Uploaded wrong patch, sorry

[DrewAPicture]

In 25860:

Inline documentation for the WP_Date_Query class in wp-includes/date.php.

• Adds a complete hash notation for the WP_Date_Query arguments array.
• Adds missing documentation for the date_query_valid_columns and get_date_sql filter hooks.

Props aeg0125 for the incremental patches.
Fixes #25552.