enmi-conf.org: comparison wp/wp-includes/date.php

equal deleted inserted replaced

-:490d5cc509ed
+:cf61fcea0001
 <?php
 /**
 * 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},
+* WP_Date_Query is a helper that allows primary query classes, such as WP_Query, to filter
-* to filter their results by date columns, by generating `WHERE` subclauses to be attached
+* their results by date columns, by generating `WHERE` subclauses to be attached to the
-* to the primary SQL query string.
+* 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 https://codex.wordpress.org/Function_Reference/WP_Query Codex page.
 *
 * @since 3.7.0
 */
 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
 	 * @var array
 	 */
 	public $queries = array();
 	/**
 	 * The default relation between top-level queries. Can be either 'AND' or 'OR'.
 	 *
 	 * @since 3.7.0
-	 * @access public
 	 * @var string
 	 */
 	public $relation = 'AND';
 	/**
 	 * The column to query against. Can be changed via the query arguments.
 	 *
 	 * @since 3.7.0
-	 * @access public
 	 * @var string
 	 */
 	public $column = 'post_date';
 	/**
 	 * The value comparison operator. Can be changed via the query arguments.
 	 *
 	 * @since 3.7.0
-	 * @access public
 	 * @var array
 	 */
 	public $compare = '=';
 	/**
 	 * Supported time-related parameter keys.
 	 *
 	 * @since 4.1.0
-	 * @access public
 	 * @var array
 	 */
 	public $time_keys = array( 'after', 'before', 'year', 'month', 'monthnum', 'week', 'w', 'dayofyear', 'day', 'dayofweek', 'dayofweek_iso', 'hour', 'minute', 'second' );
 	/**
 	 * 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.
-	 * @access public
 	 *
 	 * @param array $date_query {
 	 *     Array of date query clauses.
 	 *
 	 *     @type array {
 	 * @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'.
 	 */
 	public function __construct( $date_query, $default_column = 'post_date' ) {
 		if ( isset( $date_query['relation'] ) && 'OR' === strtoupper( $date_query['relation'] ) ) {
 			$this->relation = 'OR';
 		} else {
 			$this->relation = 'AND';
 		}
 	 * Ensures that each query-level clause has a 'relation' key, and that
 	 * each first-order clause contains all the necessary keys from
 	 * `$defaults`.
 	 *
 	 * @since 4.1.0
-	 * @access public
 	 *
 	 * @param array $queries
 	 * @param array $parent_query
 	 *
 	 * @return array Sanitized queries.
 	 * Determine whether this is a first-order clause.
 	 *
 	 * Checks to see if the current clause has any time-related keys.
 	 * If so, it's first-order.
 	 *
+	 * @since 4.1.0
+	 *
 	 * @param  array $query Query clause.
 	 * @return bool True if this is a first-order clause.
 	 */
 	protected function is_first_order_clause( $query ) {
 		$time_keys = array_intersect( $this->time_keys, array_keys( $query ) );
 	/**
 	 * Determines and validates what comparison operator to use.
 	 *
 	 * @since 3.7.0
-	 * @access public
 	 *
 	 * @param array $query A date query or a date subquery.
 	 * @return string The comparison operator.
 	 */
 	public function get_compare( $query ) {
 	 * Note that date queries with invalid date ranges are allowed to
 	 * continue (though of course no items will be found for impossible dates).
 	 * This method only generates debug notices for these cases.
 	 *
 	 * @since  4.1.0
-	 * @access public
 	 *
 	 * @param  array $date_query The date_query array.
 	 * @return bool  True if all values in the query are valid, false if one or more fail.
 	 */
 	public function validate_date_values( $date_query = array() ) {
 			'max' => 12
 		);
 		// Weeks per year.
 		if ( isset( $_year ) ) {
-			// If we have a specific year, use it to calculate number of weeks.
+			/*
-			$date = new DateTime();
+			 * If we have a specific year, use it to calculate number of weeks.
-			$date->setISODate( $_year, 53 );
+			 * Note: the number of weeks in a year is the date in which Dec 28 appears.
-			$week_count = $date->format( "W" ) === "53" ? 53 : 52;
+			 */
+			$week_count = date( 'W', mktime( 0, 0, 0, 12, 28, $_year ) );
 		} else {
 			// Otherwise set the week-count to a maximum of 53.
 			$week_count = 53;
 		}
 	 * known tables, and then, if found, have a table prefix (such as 'wp_posts.') prepended.
 	 * Prefixed column names (such as 'wp_posts.post_date') bypass this whitelist check,
 	 * and are only sanitized to remove illegal characters.
 	 *
 	 * @since 3.7.0
-	 * @access public
 	 *
 	 * @param string $column The user-supplied column name.
 	 * @return string A validated column name value.
 	 */
 	public function validate_column( $column ) {
 		global $wpdb;
 		$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.
 			 *
 			 * @param array $valid_columns An array of valid date query columns. Defaults
 					'comment_date_gmt',
 				),
 				$wpdb->users => array(
 					'user_registered',
 				),
+				$wpdb->blogs => array(
+					'registered',
+					'last_updated',
+				),
 			);
 			// If it's a known column name, add the appropriate table prefix.
 			foreach ( $known_columns as $table_name => $table_columns ) {
 				if ( in_array( $column, $table_columns ) ) {
 	/**
 	 * Generate WHERE clause to be appended to a main query.
 	 *
 	 * @since 3.7.0
-	 * @access public
 	 *
 	 * @return string MySQL WHERE clause.
 	 */
 	public function get_sql() {
 		$sql = $this->get_sql_clauses();
 		$where = $sql['where'];
 		/**
-		 * Filter the date query WHERE clause.
+		 * Filters 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.
 	}
 	/**
 	 * Generate SQL clauses to be appended to a main query.
 	 *
-	 * Called by the public {@see WP_Date_Query::get_sql()}, this method
+	 * Called by the public WP_Date_Query::get_sql(), this method is abstracted
-	 * is abstracted out to maintain parity with the other Query classes.
+	 * out to maintain parity with the other Query classes.
 	 *
 	 * @since 4.1.0
-	 * @access protected
 	 *
 	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to the main query.
 	 *
 	 *     @type string $join  SQL fragment to append to the main JOIN clause.
 	 *
 	 * If nested subqueries are found, this method recurses the tree to
 	 * produce the properly nested SQL.
 	 *
 	 * @since 4.1.0
-	 * @access protected
 	 *
 	 * @param array $query Query to parse.
 	 * @param int   $depth Optional. Number of tree levels deep we currently are.
 	 *                     Used to calculate indentation. Default 0.
 	 * @return array {
 	 *
 	 * A wrapper for get_sql_for_clause(), included here for backward
 	 * compatibility while retaining the naming convention across Query classes.
 	 *
 	 * @since  3.7.0
-	 * @access protected
 	 *
 	 * @param  array $query Date query arguments.
 	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to the main query.
 	 *
 	/**
 	 * Turns a first-order date query into SQL for a WHERE clause.
 	 *
 	 * @since  4.1.0
-	 * @access protected
 	 *
 	 * @param  array $query        Date query clause.
 	 * @param  array $parent_query Parent query of the current date query.
 	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to the main query.
 			$lt .= '=';
 			$gt .= '=';
 		}
 		// 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";
 	/**
 	 * Builds and validates a value string based on the comparison operator.
 	 *
 	 * @since 3.7.0
-	 * @access public
 	 *
 	 * @param string $compare The compare operator to use
 	 * @param string|array $value The value
 	 * @return string|false|int The value to be used in SQL or false on error.
 	 */
 				$value = array_map( 'intval', $value );
 				return $value[0] . ' AND ' . $value[1];
-			default;
+			default:
 				if ( ! is_numeric( $value ) ) {
 					return false;
 				}
 				return (int) $value;
 	/**
 	 * Builds a MySQL format date/time based on some query parameters.
 	 *
 	 * 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
 	 *
 	 * @param string|array $datetime       An array of parameters or a strotime() string
 	 * @param bool         $default_to_max Whether to round up incomplete dates. Supported by values
 	 *                                     of $datetime that are arrays, or string values that are a
 	 *                                     subset of MySQL date format ('Y', 'Y-m', 'Y-m-d', 'Y-m-d H:i').
 	 * If just hour, minute, or second is set than a normal comparison will be done.
 	 * However if multiple values are passed, a pseudo-decimal time will be created
 	 * in order to be able to accurately compare against.
 	 *
 	 * @since 3.7.0
-	 * @access public
 	 *
 	 * @param string $column The column to query against. Needs to be pre-validated!
 	 * @param string $compare The comparison operator. Needs to be pre-validated!
 	 * @param int|null $hour Optional. An hour value (0-23).
 	 * @param int|null $minute Optional. A minute value (0-59).
 			return false;
 		$format = $time = '';
 		// Hour
-		if ( $hour ) {
+		if ( null !== $hour ) {
 			$format .= '%H.';
 			$time   .= sprintf( '%02d', $hour ) . '.';
 		} else {
 			$format .= '0.';
 			$time   .= '0.';

changeset 7	cf61fcea0001
parent 5	5e2f62d02dcd
child 9	177826044cd9