/**
* Class for generating SQL clauses that filter a primary query according to date.
*
- * `WP_Date_Query` is a helper that allows primary query classes, such as {@see WP_Query},
- * to filter their results by date columns, by generating `WHERE` subclauses to be attached
- * to the primary SQL query string.
+ * WP_Date_Query is a helper that allows primary query classes, such as WP_Query, to filter
+ * their results by date columns, by generating `WHERE` subclauses to be attached to the
+ * primary SQL query string.
*
* Attempting to filter by an invalid date value (eg month=13) will generate SQL that will
* return no results. In these cases, a _doing_it_wrong() error notice is also thrown.
- * See {@link WP_Date_Query::validate_date_values()}.
+ * See WP_Date_Query::validate_date_values().
*
- * @link http://codex.wordpress.org/Function_Reference/WP_Query Codex page.
+ * @link https://codex.wordpress.org/Function_Reference/WP_Query Codex page.
*
* @since 3.7.0
*/
/**
* Array of date queries.
*
- * See {@see WP_Date_Query::__construct()} for information on date query arguments.
+ * See WP_Date_Query::__construct() for information on date query arguments.
*
* @since 3.7.0
* @access public
/**
* Constructor.
*
+ * Time-related parameters that normally require integer values ('year', 'month', 'week', 'dayofyear', 'day',
+ * 'dayofweek', 'dayofweek_iso', 'hour', 'minute', 'second') accept arrays of integers for some values of
+ * 'compare'. When 'compare' is 'IN' or 'NOT IN', arrays are accepted; when 'compare' is 'BETWEEN' or 'NOT
+ * BETWEEN', arrays of two valid values are required. See individual argument descriptions for accepted values.
+ *
* @since 3.7.0
* @since 4.0.0 The $inclusive logic was updated to include all times within the date range.
* @since 4.1.0 Introduced 'dayofweek_iso' time type parameter.
*
* @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.
- * Accepts '=', '!=', '>', '>=', '<', '<=', 'IN', 'NOT IN'. Default '='.
- * 'BETWEEN', 'NOT BETWEEN'.
- * @type string $relation Optional. The boolean relationship between the date queries.
- * Accepts 'OR', 'AND'. Default 'OR'.
+ * the `$default_column` parameter. Accepts 'post_date', 'post_date_gmt',
+ * 'post_modified','post_modified_gmt', 'comment_date', 'comment_date_gmt'.
+ * Default 'post_date'.
+ * @type string $compare Optional. The comparison operator. Accepts '=', '!=', '>', '>=', '<', '<=',
+ * 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. Default '='.
+ * @type string $relation Optional. The boolean relationship between the date queries. Accepts 'OR' or 'AND'.
+ * Default 'OR'.
* @type array {
* Optional. An array of first-order clause parameters, or another fully-formed date query.
*
- * @type string|array $before Optional. Date to retrieve posts before. Accepts strtotime()-compatible
- * string, or array of 'year', 'month', 'day' values. {
+ * @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.
* @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 after. 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|array $after {
+ * Optional. Date to retrieve posts after. Accepts `strtotime()`-compatible string,
+ * or array of 'year', 'month', 'day' values.
+ *
+ * @type string $year The four-digit year. Accepts any four-digit year. Default empty.
+ * @type string $month Optional when passing array. The month of the year. Accepts numbers 1-12.
+ * Default (string:empty)|(array:12).
+ * @type string $day Optional when passing array.The day of the month. Accepts numbers 1-31.
+ * Default (string:empty)|(array:last day of month).
* }
- * @type string $column Optional. Used to add a clause comparing a column other than the column
- * specified in the top-level $column parameter. 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 string $column Optional. Used to add a clause comparing a column other than the
+ * column specified in the top-level `$column` parameter. Accepts
+ * 'post_date', 'post_date_gmt', 'post_modified', 'post_modified_gmt',
+ * 'comment_date', 'comment_date_gmt'. Default is the value of
+ * top-level `$column`.
+ * @type string $compare Optional. The comparison operator. Accepts '=', '!=', '>', '>=',
+ * '<', '<=', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'. 'IN',
+ * 'NOT IN', 'BETWEEN', and 'NOT BETWEEN'. Comparisons support
+ * arrays in some time-related parameters. Default '='.
* @type bool $inclusive Optional. Include results from dates specified in 'before' or
* 'after'. Default false.
- * @type int $year Optional. The four-digit year 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 $dayofyear Optional. The day number of the year. Default empty.
- * Accepts numbers 1-366.
- * @type int $day Optional. The day of the month. Default empty.
- * Accepts numbers 1-31.
- * @type int $dayofweek Optional. The day number of the week. Default empty.
- * Accepts numbers 1-7 (1 is Sunday).
- * @type int $dayofweek_iso Optional. The day number of the week (ISO). Accepts numbers 1-7
- * (1 is Monday). Default empty.
- * @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.
+ * @type int|array $year Optional. The four-digit year number. Accepts any four-digit year
+ * or an array of years if `$compare` supports it. Default empty.
+ * @type int|array $month Optional. The two-digit month number. Accepts numbers 1-12 or an
+ * array of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $week Optional. The week number of the year. Accepts numbers 0-53 or an
+ * array of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $dayofyear Optional. The day number of the year. Accepts numbers 1-366 or an
+ * array of valid numbers if `$compare` supports it.
+ * @type int|array $day Optional. The day of the month. Accepts numbers 1-31 or an array
+ * of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $dayofweek Optional. The day number of the week. Accepts numbers 1-7 (1 is
+ * Sunday) or an array of valid numbers if `$compare` supports it.
+ * Default empty.
+ * @type int|array $dayofweek_iso Optional. The day number of the week (ISO). Accepts numbers 1-7
+ * (1 is Monday) or an array of valid numbers if `$compare` supports it.
+ * Default empty.
+ * @type int|array $hour Optional. The hour of the day. Accepts numbers 0-23 or an array
+ * of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $minute Optional. The minute of the hour. Accepts numbers 0-60 or an array
+ * of valid numbers if `$compare` supports it. Default empty.
+ * @type int|array $second Optional. The second of the minute. Accepts numbers 0-60 or an
+ * array of valid numbers if `$compare` supports it. Default empty.
* }
* }
* }
* 'comment_date', 'comment_date_gmt'.
*/
public function __construct( $date_query, $default_column = 'post_date' ) {
-
if ( isset( $date_query['relation'] ) && 'OR' === strtoupper( $date_query['relation'] ) ) {
$this->relation = 'OR';
} else {
$this->compare = $this->get_compare( $date_query );
$this->queries = $this->sanitize_query( $date_query );
-
- return;
}
/**
// Days per year.
if ( array_key_exists( 'year', $date_query ) ) {
- // If a year exists in the date query, we can use it to get the days.
- $max_days_of_year = date( 'z', mktime( 0, 0, 0, 12, 31, $date_query['year'] ) ) + 1;
+ /*
+ * If a year exists in the date query, we can use it to get the days.
+ * If multiple years are provided (as in a BETWEEN), use the first one.
+ */
+ if ( is_array( $date_query['year'] ) ) {
+ $_year = reset( $date_query['year'] );
+ } else {
+ $_year = $date_query['year'];
+ }
+
+ $max_days_of_year = date( 'z', mktime( 0, 0, 0, 12, 31, $_year ) ) + 1;
} else {
// otherwise we use the max of 366 (leap-year)
$max_days_of_year = 366;
);
// Weeks per year.
- if ( array_key_exists( 'year', $date_query ) ) {
- // If we have a specific year, use it to calculate number of weeks.
- $date = new DateTime();
- $date->setISODate( $date_query['year'], 53 );
- $week_count = $date->format( "W" ) === "53" ? 53 : 52;
+ if ( isset( $_year ) ) {
+ /*
+ * If we have a specific year, use it to calculate number of weeks.
+ * Note: the number of weeks in a year is the date in which Dec 28 appears.
+ */
+ $week_count = date( 'W', mktime( 0, 0, 0, 12, 28, $_year ) );
} else {
// Otherwise set the week-count to a maximum of 53.
// Hours per day.
$min_max_checks['hour'] = array(
- 'min' => 1,
+ 'min' => 0,
'max' => 23
);
continue;
}
- $is_between = $date_query[ $key ] >= $check['min'] && $date_query[ $key ] <= $check['max'];
+ // Throw a notice for each failing value.
+ foreach ( (array) $date_query[ $key ] as $_value ) {
+ $is_between = $_value >= $check['min'] && $_value <= $check['max'];
- if ( ! $is_between ) {
-
- $error = sprintf(
- /* translators: Date query invalid date message: 1: invalid value, 2: type of value, 3: minimum valid value, 4: maximum valid value */
- __( 'Invalid value %1$s for %2$s. Expected value should be between %3$s and %4$s.' ),
- '<code>' . esc_html( $date_query[ $key ] ) . '</code>',
- '<code>' . esc_html( $key ) . '</code>',
- '<code>' . esc_html( $check['min'] ) . '</code>',
- '<code>' . esc_html( $check['max'] ) . '</code>'
- );
+ if ( ! is_numeric( $_value ) || ! $is_between ) {
+ $error = sprintf(
+ /* translators: Date query invalid date message: 1: invalid value, 2: type of value, 3: minimum valid value, 4: maximum valid value */
+ __( 'Invalid value %1$s for %2$s. Expected value should be between %3$s and %4$s.' ),
+ '<code>' . esc_html( $_value ) . '</code>',
+ '<code>' . esc_html( $key ) . '</code>',
+ '<code>' . esc_html( $check['min'] ) . '</code>',
+ '<code>' . esc_html( $check['max'] ) . '</code>'
+ );
- _doing_it_wrong( __CLASS__, $error, '4.1.0' );
+ _doing_it_wrong( __CLASS__, $error, '4.1.0' );
- $valid = false;
+ $valid = false;
+ }
}
}
$valid = false;
}
- } else if ( $day_exists && $month_exists ) {
+ } elseif ( $day_exists && $month_exists ) {
/*
* 2. checking day, month combination
* We use 2012 because, as a leap year, it's the most permissive.
$valid_columns = array(
'post_date', 'post_date_gmt', 'post_modified',
'post_modified_gmt', 'comment_date', 'comment_date_gmt',
- 'user_registered',
+ 'user_registered', 'registered', 'last_updated',
);
// Attempt to detect a table prefix.
if ( false === strpos( $column, '.' ) ) {
/**
- * Filter the list of valid date query columns.
+ * Filters the list of valid date query columns.
*
* @since 3.7.0
* @since 4.1.0 Added 'user_registered' to the default recognized columns.
$wpdb->users => array(
'user_registered',
),
+ $wpdb->blogs => array(
+ 'registered',
+ 'last_updated',
+ ),
);
// If it's a known column name, add the appropriate table prefix.
$where = $sql['where'];
/**
- * Filter the date query WHERE clause.
+ * Filters the date query WHERE clause.
*
* @since 3.7.0
*
/**
* Generate SQL clauses to be appended to a main query.
*
- * Called by the public {@see WP_Date_Query::get_sql()}, this method
- * is abstracted out to maintain parity with the other Query classes.
+ * Called by the public WP_Date_Query::get_sql(), this method is abstracted
+ * out to maintain parity with the other Query classes.
*
* @since 4.1.0
* @access protected
foreach ( $query as $key => $clause ) {
if ( 'relation' === $key ) {
$relation = $query['relation'];
- } else if ( is_array( $clause ) ) {
+ } elseif ( is_array( $clause ) ) {
// This is a first-order clause.
if ( $this->is_first_order_clause( $clause ) ) {
$where_count = count( $clause_sql['where'] );
if ( ! $where_count ) {
$sql_chunks['where'][] = '';
- } else if ( 1 === $where_count ) {
+ } elseif ( 1 === $where_count ) {
$sql_chunks['where'][] = $clause_sql['where'][0];
} else {
$sql_chunks['where'][] = '( ' . implode( ' AND ', $clause_sql['where'] ) . ' )';
}
// Range queries.
- if ( ! empty( $query['after'] ) )
+ if ( ! empty( $query['after'] ) ) {
$where_parts[] = $wpdb->prepare( "$column $gt %s", $this->build_mysql_datetime( $query['after'], ! $inclusive ) );
-
- if ( ! empty( $query['before'] ) )
+ }
+ if ( ! empty( $query['before'] ) ) {
$where_parts[] = $wpdb->prepare( "$column $lt %s", $this->build_mysql_datetime( $query['before'], $inclusive ) );
-
+ }
// Specific value queries.
if ( isset( $query['year'] ) && $value = $this->build_value( $compare, $query['year'] ) )
$where_parts[] = "YEAR( $column ) $compare $value";
- if ( isset( $query['month'] ) && $value = $this->build_value( $compare, $query['month'] ) )
+ if ( isset( $query['month'] ) && $value = $this->build_value( $compare, $query['month'] ) ) {
$where_parts[] = "MONTH( $column ) $compare $value";
- else if ( isset( $query['monthnum'] ) && $value = $this->build_value( $compare, $query['monthnum'] ) )
+ } elseif ( isset( $query['monthnum'] ) && $value = $this->build_value( $compare, $query['monthnum'] ) ) {
$where_parts[] = "MONTH( $column ) $compare $value";
-
- if ( isset( $query['week'] ) && false !== ( $value = $this->build_value( $compare, $query['week'] ) ) )
+ }
+ if ( isset( $query['week'] ) && false !== ( $value = $this->build_value( $compare, $query['week'] ) ) ) {
$where_parts[] = _wp_mysql_week( $column ) . " $compare $value";
- else if ( isset( $query['w'] ) && false !== ( $value = $this->build_value( $compare, $query['w'] ) ) )
+ } elseif ( isset( $query['w'] ) && false !== ( $value = $this->build_value( $compare, $query['w'] ) ) ) {
$where_parts[] = _wp_mysql_week( $column ) . " $compare $value";
-
+ }
if ( isset( $query['dayofyear'] ) && $value = $this->build_value( $compare, $query['dayofyear'] ) )
$where_parts[] = "DAYOFYEAR( $column ) $compare $value";
*
* You can pass an array of values (year, month, etc.) with missing parameter values being defaulted to
* either the maximum or minimum values (controlled by the $default_to parameter). Alternatively you can
- * pass a string that that will be run through strtotime().
+ * pass a string that will be run through strtotime().
*
* @since 3.7.0
* @access public
'year' => intval( $matches[1] ),
);
- } else if ( preg_match( '/^(\d{4})\-(\d{2})$/', $datetime, $matches ) ) {
+ } elseif ( preg_match( '/^(\d{4})\-(\d{2})$/', $datetime, $matches ) ) {
// Y-m
$datetime = array(
'year' => intval( $matches[1] ),
'month' => intval( $matches[2] ),
);
- } else if ( preg_match( '/^(\d{4})\-(\d{2})\-(\d{2})$/', $datetime, $matches ) ) {
+ } elseif ( preg_match( '/^(\d{4})\-(\d{2})\-(\d{2})$/', $datetime, $matches ) ) {
// Y-m-d
$datetime = array(
'year' => intval( $matches[1] ),
'day' => intval( $matches[3] ),
);
- } else if ( preg_match( '/^(\d{4})\-(\d{2})\-(\d{2}) (\d{2}):(\d{2})$/', $datetime, $matches ) ) {
+ } elseif ( preg_match( '/^(\d{4})\-(\d{2})\-(\d{2}) (\d{2}):(\d{2})$/', $datetime, $matches ) ) {
// Y-m-d H:i
$datetime = array(
'year' => intval( $matches[1] ),
$format = $time = '';
// Hour
- if ( $hour ) {
+ if ( null !== $hour ) {
$format .= '%H.';
$time .= sprintf( '%02d', $hour ) . '.';
} else {
scripts.mit.edu / autoinstalls / wordpress.git / blobdiff