X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/985e04597a9f1ddc4a3b406d0fb33722e097ee8b..607b7e02d77e7326161e8ec15639052d2040f745:/wp-includes/date.php diff --git a/wp-includes/date.php b/wp-includes/date.php index 9869611e..d1f85f8c 100644 --- a/wp-includes/date.php +++ b/wp-includes/date.php @@ -2,15 +2,15 @@ /** * 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 */ @@ -18,7 +18,7 @@ class WP_Date_Query { /** * 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 @@ -65,6 +65,11 @@ class WP_Date_Query { /** * 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. @@ -75,19 +80,19 @@ class WP_Date_Query { * * @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. @@ -95,43 +100,49 @@ class WP_Date_Query { * @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. * } * } * } @@ -171,8 +182,6 @@ class WP_Date_Query { $this->compare = $this->get_compare( $date_query ); $this->queries = $this->sanitize_query( $date_query ); - - return; } /** @@ -346,10 +355,11 @@ class WP_Date_Query { // Weeks per year. if ( isset( $_year ) ) { - // If we have a specific year, use it to calculate number of weeks. - $date = new DateTime(); - $date->setISODate( $_year, 53 ); - $week_count = $date->format( "W" ) === "53" ? 53 : 52; + /* + * 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. @@ -392,7 +402,6 @@ class WP_Date_Query { } // Throw a notice for each failing value. - $is_between = true; foreach ( (array) $date_query[ $key ] as $_value ) { $is_between = $_value >= $check['min'] && $_value <= $check['max']; @@ -438,7 +447,7 @@ class WP_Date_Query { $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. @@ -482,13 +491,13 @@ class WP_Date_Query { $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. @@ -516,6 +525,10 @@ class WP_Date_Query { $wpdb->users => array( 'user_registered', ), + $wpdb->blogs => array( + 'registered', + 'last_updated', + ), ); // If it's a known column name, add the appropriate table prefix. @@ -546,7 +559,7 @@ class WP_Date_Query { $where = $sql['where']; /** - * Filter the date query WHERE clause. + * Filters the date query WHERE clause. * * @since 3.7.0 * @@ -559,8 +572,8 @@ class WP_Date_Query { /** * 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 @@ -620,7 +633,7 @@ class WP_Date_Query { 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 ) ) { @@ -629,7 +642,7 @@ class WP_Date_Query { $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'] ) . ' )'; @@ -738,16 +751,16 @@ class WP_Date_Query { 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"; @@ -844,7 +857,7 @@ class WP_Date_Query { * * 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 @@ -871,14 +884,14 @@ class WP_Date_Query { '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] ), @@ -886,7 +899,7 @@ class WP_Date_Query { '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] ), @@ -983,7 +996,7 @@ class WP_Date_Query { $format = $time = ''; // Hour - if ( $hour ) { + if ( null !== $hour ) { $format .= '%H.'; $time .= sprintf( '%02d', $hour ) . '.'; } else {