From 040d18a69f1cd52b33f45ac308398b24960a0fe1 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Mon, 21 Oct 2013 23:17:09 +0000 Subject: [PATCH] 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. Built from https://develop.svn.wordpress.org/trunk@25860 git-svn-id: http://core.svn.wordpress.org/trunk@25772 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/date.php | 110 ++++++++++++++++++++++++++++++------------- 1 file changed, 77 insertions(+), 33 deletions(-) diff --git a/wp-includes/date.php b/wp-includes/date.php index 23c9446c42..f41cae892b 100644 --- a/wp-includes/date.php +++ b/wp-includes/date.php @@ -2,35 +2,7 @@ /** * WP_Date_Query will generate a MySQL WHERE clause for the specified date-based parameters. * - * Initialize the class by passing an array of arrays of parameters. Example: - * - * $date_query = new WP_Date_Query( array( - * 'column' => 'optional, column to query against, default is post_date', - * 'compare' => 'optional, see WP_Date_Query::get_compare()', - * 'relation' => 'optional, OR or AND, how the sub-arrays should be compared, default is AND', - * array( - * 'column' => 'see above', - * 'compare' => 'see above', - * 'after' => 'string or array, see WP_Date_Query::build_mysql_datetime()', - * 'before' => 'string or array, see WP_Date_Query::build_mysql_datetime()', - * 'inclusive' => 'boolean, for after/before, whether exact value should be matched or not', - * 'year' => '4 digit int', - * 'month' => 'int, 1-12', - * 'week' => 'int, 0-53', - * 'day' => 'int, 1-31', - * 'hour' => 'int, 0-23', - * 'minute' => 'int, 0-60', - * 'second' => 'int, 0-60', - * ), - * array( - * ... - * ), - * ... - * ) ); - * - * Then call the get_sql() method to get the MySQL WHERE string: - * - * $where .= $date_query->get_sql(); + * Initialize the class by passing an array of arrays of parameters. * * @link http://codex.wordpress.org/Function_Reference/WP_Query Codex page. * @@ -74,10 +46,62 @@ class WP_Date_Query { public $compare = '='; /** - * Constructor + * Constructor. * - * @param array $date_query A date query parameter array, see class descriptor for further details. - * @param array (optional) $default_column What column name to query against. Defaults to "post_date". + * @param array $date_query { + * One or more associative arrays of date query parameters. + * + * @type array { + * @type string $column Optional. The column to query against. If undefined, inherits the value of + * the $default_column parameter. Default 'post_date'. Accepts 'post_date', + * 'post_date_gmt', 'post_modified','post_modified_gmt', 'comment_date', + * 'comment_date_gmt'. + * @type string $compare Optional. The comparison operator. + * Default '='. Accepts '=', '!=', '>', '>=', '<', '<=', 'IN', 'NOT IN', + * 'BETWEEN', 'NOT BETWEEN'. + * @type string $relation Optional. The boolean relationship between the date queryies. + * Default 'OR'. Accepts 'OR', 'AND'. + * @type array { + * @type string|array $before Optional. Date to retrieve posts before. Accepts strtotime()-compatible + * string, or array of 'year', 'month', 'day' values. { + * + * @type string $year The four-digit year. Default empty. Accepts any four-digit year. + * @type string $month Optional when passing array.The month of the year. + * Default (string:empty)|(array:1). Accepts numbers 1-12. + * @type string $day Optional when passing array.The day of the month. + * Default (string:empty)|(array:1). Accepts numbers 1-31. + * } + * @type string|array $after Optional. Date to retrieve posts before. Accepts strtotime()-compatible + * string, or array of 'year', 'month', 'day' values. { + * + * @type string $year The four-digit year. Default empty. Accepts any four-digit year. + * @type string $month Optional when passing array.The month of the year. + * Default (string:empty)|(array:12). Accepts numbers 1-12. + * @type string $day Optional when passing array.The day of the month. + * Default (string:empty)|(array:last day of month). Accepts numbers 1-31. + * } + * @type string $column Optional. Used to add a clause comparing a column other than the column + * specified in the top-level $column paramater. Default is the value + * of top-level $column. Accepts 'post_date', 'post_date_gmt', + * 'post_modified', 'post_modified_gmt', 'comment_date', 'comment_date_gmt'. + * @type string $compare Optional. The comparison operator. Default '='. Accepts '=', '!=', + * '>', '>=', '<', '<=', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. + * @type bool $inclusive Optional. Include results from dates specified in 'before' or 'after'. + * Default. Accepts. + * @type int $year Optional. The four-digit near number. Default empty. Accepts any + * four-digit year. + * @type int $month Optional. The two-digit month number. Default empty. Accepts numbers 1-12. + * @type int $week Optional. The week number of the year. Default empty. Accepts numbers 0-53. + * @type int $day Optional. The day of the month. Default empty. Accepts numbers 1-31. + * @type int $hour Optional. The hour of the day. Default empty. Accepts numbers 0-23. + * @type int $minute Optional. The minute of the hour. Default empty. Accepts numbers 0-60. + * @type int $second Optional. The second of the minute. Default empty. Accepts numbers 0-60. + * } + * } + * } + * @param array $default_column Optional. Default column to query against. Default 'post_date'. + * Accepts 'post_date', 'post_date_gmt', 'post_modified', 'post_modified_gmt', + * 'comment_date', 'comment_date_gmt'. */ function __construct( $date_query, $default_column = 'post_date' ) { if ( empty( $date_query ) || ! is_array( $date_query ) ) @@ -136,7 +160,19 @@ class WP_Date_Query { * @return string A validated column name value. */ public function validate_column( $column ) { - if ( ! in_array( $column, apply_filters( 'date_query_valid_columns', array( 'post_date', 'post_date_gmt', 'post_modified', 'post_modified_gmt', 'comment_date', 'comment_date_gmt' ) ) ) ) + $valid_columns = array( + 'post_date', 'post_date_gmt', 'post_modified', + 'post_modified_gmt', 'comment_date', 'comment_date_gmt' + ); + /** + * Filter the list of valid date query columns. + * + * @since 3.7.0 + * + * @param array $valid_columns An array of valid date query columns. Defaults are 'post_date', 'post_date_gmt', + * 'post_modified', 'post_modified_gmt', 'comment_date', 'comment_date_gmt' + */ + if ( ! in_array( $column, apply_filters( 'date_query_valid_columns', $valid_columns ) ) ) $column = 'post_date'; return $column; @@ -168,6 +204,14 @@ class WP_Date_Query { else $where = ''; + /** + * Filter the date query WHERE clause. + * + * @since 3.7.0 + * + * @param string $where WHERE clause of the date query. + * @param WP_Date_Query $this The WP_Date_Query instance. + */ return apply_filters( 'get_date_sql', $where, $this ); }