Add types to timecop functions

php_timecop.h

@@ -192,6 +192,22 @@ struct timecop_override_class_entry {
 #define call_php_function_with_3_params(function_name, retval, arg1, arg2, arg3) \
 	_call_php_function_with_3_params(function_name, retval, arg1, arg2, arg3 TSRMLS_CC)
 
+#if PHP_VERSION_ID >= 80000
+#define TIMECOP_PARSE_TRAVEL_ARGS(timeval) \
+	if (parse_travel_freeze_arguments(&timeval, INTERNAL_FUNCTION_PARAM_PASSTHRU) > 0) { \
+		RETURN_THROWS(); \
+	}
+#else
+// PHP 7.x needs some extra error handling code to match up with PHP 8.
+#define TIMECOP_PARSE_TRAVEL_ARGS(timeval) \
+	if (parse_travel_freeze_arguments(&timeval, INTERNAL_FUNCTION_PARAM_PASSTHRU) > 0) { \
+		zend_type_error("%s(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, N/A given", get_active_function_name()); \
+		return; \
+	}
+#endif
+
+#define TIMECOP_PARSE_FREEZE_ARGS TIMECOP_PARSE_TRAVEL_ARGS
+
 /* In every utility function you add that needs to use variables
    in php_timecop_globals, call TSRMLS_FETCH(); after declaring other
    variables used by that function, or better yet, pass in TSRMLS_CC

tests/func_015.phpt

@@ -0,0 +1,59 @@
+--TEST--
+Test for timecop_travel (invalid arguments)
+--SKIPIF--
+<?php
+$required_func = array("timecop_travel");
+$required_version = '7.0';
+include(__DIR__."/tests-skipcheck.inc.php");
+--INI--
+date.timezone=America/Los_Angeles
+timecop.func_override=0
+--FILE--
+<?php
+declare(strict_types=1);
+
+// Simplified version of:
+// https://github.com/symfony/polyfill/blob/6db783b3a48077f7102b6d7be6314d871eb7898c/src/Php80/Php80.php#L28-L58
+function var_type($value): string
+{
+    switch (true) {
+        case null === $value: return 'null';
+        case \is_bool($value): return 'bool';
+        case \is_string($value): return 'string';
+        case \is_array($value): return 'array';
+        case \is_int($value): return 'int';
+        case \is_float($value): return 'float';
+        case \is_object($value): return \get_class($value);
+    }
+
+    return 'unknown';
+}
+
+foreach (['', (object) [], '1234', 4.5, true, new \DateTimeImmutable(), new \DateTime(), 64] as $input) {
+    try {
+        var_dump(timecop_travel($input));
+    } catch (TypeError $e) {
+        $message = $e->getMessage();
+
+        if (PHP_VERSION_ID >= 80300) {
+            // PHP 8.3+ outputs "true given" instead of "bool given".
+            $message = str_replace('true given', 'bool given', $message);
+        }
+
+        // Workaround exception message not including type in PHP 7 so the same test can be used for both.
+        if (PHP_MAJOR_VERSION === 7) {
+            $message = str_replace('N/A given', var_type($input).' given', $message);
+        }
+
+        echo $message, "\n";
+    }
+}
+--EXPECT--
+timecop_travel(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, string given
+timecop_travel(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, stdClass given
+timecop_travel(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, string given
+timecop_travel(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, float given
+timecop_travel(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, bool given
+bool(true)
+bool(true)
+bool(true)

tests/func_016.phpt

@@ -0,0 +1,59 @@
+--TEST--
+Test for timecop_freeze (invalid arguments)
+--SKIPIF--
+<?php
+$required_func = array("timecop_freeze");
+$required_version = '7.0';
+include(__DIR__."/tests-skipcheck.inc.php");
+--INI--
+date.timezone=America/Los_Angeles
+timecop.func_override=0
+--FILE--
+<?php
+declare(strict_types=1);
+
+// Simplified version of:
+// https://github.com/symfony/polyfill/blob/6db783b3a48077f7102b6d7be6314d871eb7898c/src/Php80/Php80.php#L28-L58
+function var_type($value): string
+{
+    switch (true) {
+        case null === $value: return 'null';
+        case \is_bool($value): return 'bool';
+        case \is_string($value): return 'string';
+        case \is_array($value): return 'array';
+        case \is_int($value): return 'int';
+        case \is_float($value): return 'float';
+        case \is_object($value): return \get_class($value);
+    }
+
+    return 'unknown';
+}
+
+foreach (['', (object) [], '1234', 4.5, true, new \DateTimeImmutable(), new \DateTime(), 64] as $input) {
+    try {
+        var_dump(timecop_freeze($input));
+    } catch (TypeError $e) {
+        $message = $e->getMessage();
+
+        if (PHP_VERSION_ID >= 80300) {
+            // PHP 8.3+ outputs "true given" instead of "bool given".
+            $message = str_replace('true given', 'bool given', $message);
+        }
+
+        // Workaround exception message not including type in PHP 7 so the same test can be used for both.
+        if (PHP_MAJOR_VERSION === 7) {
+            $message = str_replace('N/A given', var_type($input).' given', $message);
+        }
+
+        echo $message, "\n";
+    }
+}
+--EXPECT--
+timecop_freeze(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, string given
+timecop_freeze(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, stdClass given
+timecop_freeze(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, string given
+timecop_freeze(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, float given
+timecop_freeze(): Argument #1 ($timestamp) must be of type DateTimeInterface|int, bool given
+bool(true)
+bool(true)
+bool(true)

tests/func_017.phpt

@@ -0,0 +1,28 @@
+--TEST--
+Test for timecop_scale (invalid arguments)
+--SKIPIF--
+<?php
+$required_func = array("timecop_scale");
+$required_version = '7.0';
+include(__DIR__."/tests-skipcheck.inc.php");
+--INI--
+date.timezone=America/Los_Angeles
+timecop.func_override=0
+--FILE--
+<?php
+declare(strict_types=1);
+
+foreach (['', (object) [], '1234', 4.5, true, -10] as $input) {
+    try {
+        var_dump(timecop_scale($input));
+    } catch (TypeError $e) {
+        echo $e->getMessage(), "\n";
+    }
+}
+--EXPECTREGEX--
+timecop_scale\(\)( expects parameter 1 to be|: Argument #1 \(\$scale\) must be of type) (integer|int), string given
+timecop_scale\(\)( expects parameter 1 to be|: Argument #1 \(\$scale\) must be of type) (integer|int), (object|stdClass) given
+timecop_scale\(\)( expects parameter 1 to be|: Argument #1 \(\$scale\) must be of type) (integer|int), string given
+timecop_scale\(\)( expects parameter 1 to be|: Argument #1 \(\$scale\) must be of type) (integer|int), float given
+timecop_scale\(\)( expects parameter 1 to be|: Argument #1 \(\$scale\) must be of type) (integer|int), (bool|boolean|true) given
+bool\(false\)

timecop.stub.php

@@ -0,0 +1,32 @@
+<?php
+/*
+MIT License
+
+Copyright (c) 2012-2017 Yoshio HANAWA
+Copyright (c) 2021 Wider Plan Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+ */
+
+// Use build/gen_stub.php from PHP 8 source code checkout to create .h contents.
+
+function timecop_freeze(\DateTimeInterface|int $timestamp): bool {}
+function timecop_travel(\DateTimeInterface|int $timestamp): bool {}
+function timecop_scale(int $scale): bool {}
+function timecop_return(): bool {}

timecop_php7.c

@@ -200,7 +200,12 @@ static void _timecop_call_mktime(INTERNAL_FUNCTION_PARAMETERS, const char *mktim
 static int get_mock_timeval(tc_timeval *fixed, const tc_timeval *now);
 static inline zend_long mock_timestamp();
 
-static int get_timeval_from_datetime(tc_timeval *tp, zval *dt);
+zend_always_inline static int parse_travel_freeze_arguments(tc_timeval *ret, INTERNAL_FUNCTION_PARAMETERS);
+#if PHP_VERSION_ID >= 80000
+zend_always_inline static int get_timeval_from_datetime(tc_timeval *tp, zend_object *dt, zend_class_entry *dt_ce);
+#else
+zend_always_inline static int get_timeval_from_datetime(tc_timeval *tp, zval *dt);
+#endif
 static int get_current_time(tc_timeval *now);
 
 static void _timecop_orig_datetime_constructor(INTERNAL_FUNCTION_PARAMETERS, int immutable);
@@ -875,19 +880,9 @@ static void _timecop_call_mktime(INTERNAL_FUNCTION_PARAMETERS, const char *mktim
    Time travel to specified timestamp and freeze */
 PHP_FUNCTION(timecop_freeze)
 {
-	zval *dt;
-	zend_long timestamp;
 	tc_timeval freezed_tv;
 
-	if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "O", &dt, TIMECOP_G(ce_DateTimeInterface)) != FAILURE) {
-		get_timeval_from_datetime(&freezed_tv, dt);
-	} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "l", &timestamp) != FAILURE) {
-		freezed_tv.sec = timestamp;
-		freezed_tv.usec = 0;
-	} else {
-		php_error_docref(NULL, E_WARNING, "This function accepts either (DateTimeInterface) OR (int) as arguments.");
-		RETURN_FALSE;
-	}
+	TIMECOP_PARSE_FREEZE_ARGS(freezed_tv);
 
 	TIMECOP_G(timecop_mode) = TIMECOP_MODE_FREEZE;
 	TIMECOP_G(freezed_time) = freezed_tv;
@@ -904,19 +899,9 @@ PHP_FUNCTION(timecop_freeze)
    Time travel to specified timestamp */
 PHP_FUNCTION(timecop_travel)
 {
-	zval *dt;
-	zend_long timestamp;
 	tc_timeval now, mock_tv;
 
-	if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "O", &dt, TIMECOP_G(ce_DateTimeInterface)) != FAILURE) {
-		get_timeval_from_datetime(&mock_tv, dt);
-	} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "l", &timestamp) != FAILURE) {
-		mock_tv.sec = timestamp;
-		mock_tv.usec = 0;
-	} else {
-		php_error_docref(NULL, E_WARNING, "This function accepts either (DateTimeInterface) OR (int) as arguments.");
-		RETURN_FALSE;
-	}
+	TIMECOP_PARSE_TRAVEL_ARGS(mock_tv);
 
 	TIMECOP_G(timecop_mode) = TIMECOP_MODE_TRAVEL;
 	get_current_time(&now);
@@ -938,9 +923,10 @@ PHP_FUNCTION(timecop_scale)
 	zend_long scale;
 	tc_timeval now, mock_time;
 
-	if (zend_parse_parameters(ZEND_NUM_ARGS(), "l", &scale) == FAILURE) {
-		RETURN_FALSE;
-	}
+	ZEND_PARSE_PARAMETERS_START(1, 1);
+		Z_PARAM_LONG(scale);
+	ZEND_PARSE_PARAMETERS_END();
+
 	if (scale < 0) {
 		RETURN_FALSE;
 	}
@@ -1224,14 +1210,71 @@ static zend_long mock_timestamp()
 	return tv.sec;
 }
 
-static int get_timeval_from_datetime(tc_timeval *tp, zval *dt)
+// Used by timecop_travel() and timecop_freeze() to parse common arguments.
+zend_always_inline static int parse_travel_freeze_arguments(tc_timeval *ret, INTERNAL_FUNCTION_PARAMETERS)
+{
+	zval *dt_zval;
+	zend_object *dt_obj;
+	zend_long timestamp;
+
+#if PHP_VERSION_ID >= 80000
+	ZEND_PARSE_PARAMETERS_START(1, 1);
+		Z_PARAM_OBJ_OF_CLASS_OR_LONG(dt_obj, TIMECOP_G(ce_DateTimeInterface), timestamp);
+	ZEND_PARSE_PARAMETERS_END_EX(return 1;);
+
+	if (dt_obj) {
+		get_timeval_from_datetime(ret, dt_obj, dt_obj->ce);
+	} else {
+		ret->sec = timestamp;
+		ret->usec = 0;
+	}
+#else
+	// Cannot use ZEND_PARSE_PARAMS_THROW as it cannot output required type is "int|DateTime".
+	if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "O", &dt_zval, TIMECOP_G(ce_DateTimeInterface)) != FAILURE) {
+		ZEND_PARSE_PARAMETERS_START_EX(ZEND_PARSE_PARAMS_QUIET, 1, 1)
+			Z_PARAM_OBJECT_OF_CLASS(dt_zval, TIMECOP_G(ce_DateTimeInterface));
+		ZEND_PARSE_PARAMETERS_END_EX(return 1;);
+
+		get_timeval_from_datetime(ret, dt_zval);
+	} else {
+		ZEND_PARSE_PARAMETERS_START_EX(ZEND_PARSE_PARAMS_QUIET, 1, 1)
+			Z_PARAM_LONG(timestamp);
+		ZEND_PARSE_PARAMETERS_END_EX(return 1;);
+
+		ret->sec = timestamp;
+		ret->usec = 0;
+	}
+#endif
+
+	return 0;
+}
+
+#if PHP_VERSION_ID >= 80000
+zend_always_inline static int get_timeval_from_datetime(tc_timeval *tp, zend_object *dt, zend_class_entry *dt_ce)
+{
+	zval sec, usec;
+	zval u_str;
+
+	zend_call_method_with_0_params(dt, dt_ce, NULL, "gettimestamp", &sec);
+	ZVAL_STRING(&u_str, "u");
+	zend_call_method_with_1_params(dt, dt_ce, NULL, "format", &usec, &u_str);
+	zval_ptr_dtor(&u_str);
+	convert_to_long(&usec);
+
+	tp->sec = Z_LVAL(sec);
+	tp->usec = Z_LVAL(usec);
+
+	return 0;
+}
+#else
+zend_always_inline static int get_timeval_from_datetime(tc_timeval *tp, zval *dt)
 {
 	zval sec, usec;
 	zval u_str;
 
-	call_php_method_with_0_params(dt, Z_OBJCE_P(dt), "gettimestamp", &sec);
+	zend_call_method_with_0_params(dt, Z_OBJCE_P(dt), NULL, "gettimestamp", &sec);
 	ZVAL_STRING(&u_str, "u");
-	call_php_method_with_1_params(dt, Z_OBJCE_P(dt), "format", &usec, &u_str);
+	zend_call_method_with_1_params(dt, Z_OBJCE_P(dt), NULL, "format", &usec, &u_str);
 	zval_ptr_dtor(&u_str);
 	convert_to_long(&usec);
 
@@ -1240,6 +1283,7 @@ static int get_timeval_from_datetime(tc_timeval *tp, zval *dt)
 
 	return 0;
 }
+#endif
 
 static int get_current_time(tc_timeval *now)
 {

timecop_php8_arginfo.h

@@ -23,19 +23,17 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
  */
 
-ZEND_BEGIN_ARG_INFO_EX(arginfo_timecop_freeze, 0, 0, 1)
-	ZEND_ARG_INFO(0, timestamp)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_timecop_freeze, 0, 1, _IS_BOOL, 0)
+	ZEND_ARG_OBJ_TYPE_MASK(0, timestamp, DateTimeInterface, MAY_BE_LONG, NULL)
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_INFO_EX(arginfo_timecop_travel, 0, 0, 1)
-	ZEND_ARG_INFO(0, timestamp)
-ZEND_END_ARG_INFO()
+#define arginfo_timecop_travel arginfo_timecop_freeze
 
-ZEND_BEGIN_ARG_INFO_EX(arginfo_timecop_scale, 0, 0, 1)
-	ZEND_ARG_INFO(0, scale)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_timecop_scale, 0, 1, _IS_BOOL, 0)
+	ZEND_ARG_TYPE_INFO(0, scale, IS_LONG, 0)
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_INFO(arginfo_timecop_return, 0)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_timecop_return, 0, 0, _IS_BOOL, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_timecop_time, 0, 0, IS_LONG, 0)