Commit 930063078d for wordpress.org
commit 930063078d6be3c0143df6e51d0b3cb945a07b0d
Author: westonruter <westonruter@git.wordpress.org>
Date: Wed Nov 4 20:00:14 2026 +0000
Date/Time: Correct argument types in `WP_Date_Query`.
The PHPStan baseline held eight `argument.type` errors for `WP_Date_Query`, caused by docblocks narrower than the input the methods actually handle and by an unused parameter. Since `build_value()` was introduced it has been documented as taking a string or an array, yet `build_time_query()` has always passed it integers or null. And when nested queries were added, `get_sql_for_subquery()` passed an empty string for the `$parent_query` array that `get_sql_for_clause()` never reads.
No path of `build_mysql_datetime()` returns false, though its `@return` tag said otherwise. An unparseable string has always resulted in the Unix epoch, obtained by passing false as the timestamp to `gmdate()`. That fallback now passes 0 and is documented, and its test asserts the fixed value instead of computing it, which also corrects a comment claiming the test was time-dependent.
The PHPStan types also go further than the published `@param` tags in describing valid input. The comparison operator is limited to the ten accepted by `get_compare()`, which are put directly into SQL. Date values are limited to non-negative integers or numeric strings, because `absint()` would silently turn a negative value positive. Non-numeric values are still filtered out at runtime, so there is no change in behavior.
Developed in https://github.com/WordPress/wordpress-develop/pull/15469.
Follow-up to r25139, r29923, r45876.
Props pwtyler, westonruter.
See #65817.
Built from https://develop.svn.wordpress.org/trunk@65262
git-svn-id: http://core.svn.wordpress.org/trunk@64411 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-includes/class-wp-date-query.php b/wp-includes/class-wp-date-query.php
index abfacce6cd..cad38e1816 100644
--- a/wp-includes/class-wp-date-query.php
+++ b/wp-includes/class-wp-date-query.php
@@ -13,6 +13,8 @@
* @link https://developer.wordpress.org/reference/classes/wp_query/
*
* @since 3.7.0
+ *
+ * @phpstan-type Date_Query_Compare '='|'!='|'>'|'>='|'<'|'<='|'IN'|'NOT IN'|'BETWEEN'|'NOT BETWEEN'
*/
#[AllowDynamicProperties]
class WP_Date_Query {
@@ -47,6 +49,7 @@ class WP_Date_Query {
*
* @since 3.7.0
* @var string
+ * @phpstan-var Date_Query_Compare
*/
public $compare = '=';
@@ -252,6 +255,8 @@ class WP_Date_Query {
*
* @param array $query A date query or a date subquery.
* @return string The comparison operator.
+ *
+ * @phpstan-return Date_Query_Compare
*/
public function get_compare( $query ) {
if ( ! empty( $query['compare'] )
@@ -697,7 +702,7 @@ class WP_Date_Query {
* }
*/
protected function get_sql_for_subquery( $query ) {
- return $this->get_sql_for_clause( $query, '' );
+ return $this->get_sql_for_clause( $query, array() );
}
/**
@@ -808,9 +813,12 @@ class WP_Date_Query {
*
* @since 3.7.0
*
- * @param string $compare The compare operator to use.
- * @param string|array $value The value.
+ * @param string $compare The compare operator to use.
+ * @param string|int|array<int|string>|null $value The value.
* @return string|false|int The value to be used in SQL or false on error.
+ *
+ * @phpstan-param Date_Query_Compare $compare
+ * @phpstan-param int|numeric-string|array<int|numeric-string>|null $value
*/
public function build_value( $compare, $value ) {
if ( ! isset( $value ) ) {
@@ -873,7 +881,17 @@ class WP_Date_Query {
* 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').
* Default: false.
- * @return string|false A MySQL format date/time or false on failure.
+ * @return string A MySQL format date/time. An unparseable string results in the Unix epoch
+ * (`1970-01-01 00:00:00`).
+ *
+ * @phpstan-param string|array{
+ * year?: int<0, max>|numeric-string,
+ * month?: int<0, max>|numeric-string,
+ * day?: int<0, max>|numeric-string,
+ * hour?: int<0, max>|numeric-string,
+ * minute?: int<0, max>|numeric-string,
+ * second?: int<0, max>|numeric-string,
+ * } $datetime
*/
public function build_mysql_datetime( $datetime, $default_to_max = false ) {
if ( ! is_array( $datetime ) ) {
@@ -922,7 +940,7 @@ class WP_Date_Query {
$dt = date_create( $datetime, $wp_timezone );
if ( false === $dt ) {
- return gmdate( 'Y-m-d H:i:s', false );
+ return gmdate( 'Y-m-d H:i:s', 0 );
}
return $dt->setTimezone( $wp_timezone )->format( 'Y-m-d H:i:s' );
@@ -931,7 +949,7 @@ class WP_Date_Query {
$datetime = array_map( 'absint', $datetime );
- $datetime['year'] ??= current_time( 'Y' );
+ $datetime['year'] ??= (int) current_time( 'Y' );
$datetime['month'] ??= ( $default_to_max ) ? 12 : 1;
$datetime['day'] ??= ( $default_to_max ) ? (int) gmdate( 't', mktime( 0, 0, 0, $datetime['month'], 1, $datetime['year'] ) ) : 1;
$datetime['hour'] ??= ( $default_to_max ) ? 23 : 0;
@@ -958,6 +976,8 @@ class WP_Date_Query {
* @param int|null $minute Optional. A minute value (0-59).
* @param int|null $second Optional. A second value (0-59).
* @return string|false A query part or false on failure.
+ *
+ * @phpstan-param Date_Query_Compare $compare
*/
public function build_time_query( $column, $compare, $hour = null, $minute = null, $second = null ) {
global $wpdb;
diff --git a/wp-includes/version.php b/wp-includes/version.php
index c39f380b2d..01e4e7bb6c 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.2-beta4-65261';
+$wp_version = '7.2-beta4-65262';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.