Skip to content

Commit 58911ba

Browse files
committed
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 #15469. Follow-up to r25139, r29923, r45876. Props pwtyler, westonruter. See #65817. git-svn-id: https://develop.svn.wordpress.org/trunk@65262 602fd350-edb4-49c9-b593-d223f7449a82
1 parent a99e724 commit 58911ba

3 files changed

Lines changed: 28 additions & 30 deletions

File tree

‎src/wp-includes/class-wp-date-query.php‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313
* @link https://developer.wordpress.org/reference/classes/wp_query/
1414
*
1515
* @since 3.7.0
16+
*
17+
* @phpstan-type Date_Query_Compare '='|'!='|'>'|'>='|'<'|'<='|'IN'|'NOT IN'|'BETWEEN'|'NOT BETWEEN'
1618
*/
1719
#[AllowDynamicProperties]
1820
class WP_Date_Query {
@@ -47,6 +49,7 @@ class WP_Date_Query {
4749
*
4850
* @since 3.7.0
4951
* @var string
52+
* @phpstan-var Date_Query_Compare
5053
*/
5154
public $compare = '=';
5255

@@ -252,6 +255,8 @@ protected function is_first_order_clause( $query ) {
252255
*
253256
* @param array $query A date query or a date subquery.
254257
* @return string The comparison operator.
258+
*
259+
* @phpstan-return Date_Query_Compare
255260
*/
256261
public function get_compare( $query ) {
257262
if ( ! empty( $query['compare'] )
@@ -697,7 +702,7 @@ protected function get_sql_for_query( $query, $depth = 0 ) {
697702
* }
698703
*/
699704
protected function get_sql_for_subquery( $query ) {
700-
return $this->get_sql_for_clause( $query, '' );
705+
return $this->get_sql_for_clause( $query, array() );
701706
}
702707

703708
/**
@@ -808,9 +813,12 @@ protected function get_sql_for_clause( $query, $parent_query ) {
808813
*
809814
* @since 3.7.0
810815
*
811-
* @param string $compare The compare operator to use.
812-
* @param string|array $value The value.
816+
* @param string $compare The compare operator to use.
817+
* @param string|int|array<int|string>|null $value The value.
813818
* @return string|false|int The value to be used in SQL or false on error.
819+
*
820+
* @phpstan-param Date_Query_Compare $compare
821+
* @phpstan-param int|numeric-string|array<int|numeric-string>|null $value
814822
*/
815823
public function build_value( $compare, $value ) {
816824
if ( ! isset( $value ) ) {
@@ -873,7 +881,17 @@ public function build_value( $compare, $value ) {
873881
* of $datetime that are arrays, or string values that are a
874882
* subset of MySQL date format ('Y', 'Y-m', 'Y-m-d', 'Y-m-d H:i').
875883
* Default: false.
876-
* @return string|false A MySQL format date/time or false on failure.
884+
* @return string A MySQL format date/time. An unparseable string results in the Unix epoch
885+
* (`1970-01-01 00:00:00`).
886+
*
887+
* @phpstan-param string|array{
888+
* year?: int<0, max>|numeric-string,
889+
* month?: int<0, max>|numeric-string,
890+
* day?: int<0, max>|numeric-string,
891+
* hour?: int<0, max>|numeric-string,
892+
* minute?: int<0, max>|numeric-string,
893+
* second?: int<0, max>|numeric-string,
894+
* } $datetime
877895
*/
878896
public function build_mysql_datetime( $datetime, $default_to_max = false ) {
879897
if ( ! is_array( $datetime ) ) {
@@ -922,7 +940,7 @@ public function build_mysql_datetime( $datetime, $default_to_max = false ) {
922940
$dt = date_create( $datetime, $wp_timezone );
923941

924942
if ( false === $dt ) {
925-
return gmdate( 'Y-m-d H:i:s', false );
943+
return gmdate( 'Y-m-d H:i:s', 0 );
926944
}
927945

928946
return $dt->setTimezone( $wp_timezone )->format( 'Y-m-d H:i:s' );
@@ -931,7 +949,7 @@ public function build_mysql_datetime( $datetime, $default_to_max = false ) {
931949

932950
$datetime = array_map( 'absint', $datetime );
933951

934-
$datetime['year'] ??= current_time( 'Y' );
952+
$datetime['year'] ??= (int) current_time( 'Y' );
935953
$datetime['month'] ??= ( $default_to_max ) ? 12 : 1;
936954
$datetime['day'] ??= ( $default_to_max ) ? (int) gmdate( 't', mktime( 0, 0, 0, $datetime['month'], 1, $datetime['year'] ) ) : 1;
937955
$datetime['hour'] ??= ( $default_to_max ) ? 23 : 0;
@@ -958,6 +976,8 @@ public function build_mysql_datetime( $datetime, $default_to_max = false ) {
958976
* @param int|null $minute Optional. A minute value (0-59).
959977
* @param int|null $second Optional. A second value (0-59).
960978
* @return string|false A query part or false on failure.
979+
*
980+
* @phpstan-param Date_Query_Compare $compare
961981
*/
962982
public function build_time_query( $column, $compare, $hour = null, $minute = null, $second = null ) {
963983
global $wpdb;

‎tests/phpstan/baselines/argument.type.neon‎

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -708,26 +708,6 @@ parameters:
708708
identifier: argument.type
709709
count: 1
710710
path: ../../../src/wp-includes/class-wp-customize-manager.php
711-
-
712-
message: '#^Parameter \#2 \$parent_query of method WP_Date_Query\:\:get_sql_for_clause\(\) expects array, string given\.$#'
713-
identifier: argument.type
714-
count: 1
715-
path: ../../../src/wp-includes/class-wp-date-query.php
716-
-
717-
message: '#^Parameter \#2 \$timestamp of function gmdate expects int, false given\.$#'
718-
identifier: argument.type
719-
count: 1
720-
path: ../../../src/wp-includes/class-wp-date-query.php
721-
-
722-
message: '#^Parameter \#2 \$value of method WP_Date_Query\:\:build_value\(\) expects array\|string, int given\.$#'
723-
identifier: argument.type
724-
count: 3
725-
path: ../../../src/wp-includes/class-wp-date-query.php
726-
-
727-
message: '#^Parameter \#2 \$value of method WP_Date_Query\:\:build_value\(\) expects array\|string, int\|null given\.$#'
728-
identifier: argument.type
729-
count: 3
730-
path: ../../../src/wp-includes/class-wp-date-query.php
731711
-
732712
message: '#^Parameter \#1 \$postarr of function wp_insert_post expects array\{ID\?\: int, post_author\?\: int, post_date\?\: string, post_date_gmt\?\: string, post_content\?\: string, post_content_filtered\?\: string, post_title\?\: string, post_excerpt\?\: string, \.\.\., \.\.\.\}, array\<string\> given\.$#'
733713
identifier: argument.type

‎tests/phpunit/tests/date/query.php‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -524,10 +524,8 @@ public function test_build_value_compare_default_value_non_numeric() {
524524
public function test_build_mysql_datetime_datetime_non_array() {
525525
$q = new WP_Date_Query( array() );
526526

527-
// This might be a fragile test if it takes longer than 1 second to run.
528-
$found = $q->build_mysql_datetime( 'foo' );
529-
$expected = gmdate( 'Y-m-d H:i:s', false );
530-
$this->assertSame( $expected, $found );
527+
$found = $q->build_mysql_datetime( 'foo' );
528+
$this->assertSame( '1970-01-01 00:00:00', $found );
531529
}
532530

533531
/**

0 commit comments

Comments
 (0)