Add types to timecop functions

php_timecop.h

@@ -194,6 +194,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,61 @@
+--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, false, 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,false} given" instead of "bool given".
+            $message = str_replace('true given', 'bool given', $message);
+            $message = str_replace('false 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
+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,61 @@
+--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, false, 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,false} given" instead of "bool given".
+            $message = str_replace('true given', 'bool given', $message);
+            $message = str_replace('false 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
+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\)

tests/refl_006.phpt

@@ -0,0 +1,47 @@
+--TEST--
+Check extension functions reflection data
+--SKIPIF--
+<?php
+$required_version = '5.0';
+$required_version_less_than = '8.0';
+$required_func = array();
+$required_class = array();
+$required_method = array();
+include(__DIR__."/tests-skipcheck.inc.php");
+--INI--
+date.timezone=America/Los_Angeles
+timecop.func_override=0
+--FILE--
+<?php
+
+echo trim(new \ReflectionFunction('timecop_travel')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_freeze')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_scale')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_return'));
+--EXPECT--
+Function [ <internal:timecop> function timecop_travel ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> $timestamp ]
+  }
+}
+
+Function [ <internal:timecop> function timecop_freeze ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> $timestamp ]
+  }
+}
+
+Function [ <internal:timecop> function timecop_scale ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> $scale ]
+  }
+}
+
+Function [ <internal:timecop> function timecop_return ] {
+
+  - Parameters [0] {
+  }
+}

tests/refl_006_php80.phpt

@@ -0,0 +1,51 @@
+--TEST--
+Check extension functions reflection data
+--SKIPIF--
+<?php
+$required_version = '8.0';
+$required_version_less_than = '8.2';
+$required_func = array();
+$required_class = array();
+$required_method = array();
+include(__DIR__."/tests-skipcheck.inc.php");
+--INI--
+date.timezone=America/Los_Angeles
+timecop.func_override=0
+--FILE--
+<?php
+
+echo trim(new \ReflectionFunction('timecop_travel')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_freeze')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_scale')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_return'));
+--EXPECT--
+Function [ <internal:timecop> function timecop_travel ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> DateTimeInterface|int $timestamp ]
+  }
+  - Return [ bool ]
+}
+
+Function [ <internal:timecop> function timecop_freeze ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> DateTimeInterface|int $timestamp ]
+  }
+  - Return [ bool ]
+}
+
+Function [ <internal:timecop> function timecop_scale ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> int $scale ]
+  }
+  - Return [ bool ]
+}
+
+Function [ <internal:timecop> function timecop_return ] {
+
+  - Parameters [0] {
+  }
+  - Return [ bool ]
+}

tests/refl_006_php83.phpt

@@ -0,0 +1,50 @@
+--TEST--
+Check extension functions reflection data
+--SKIPIF--
+<?php
+$required_version = '8.2';
+$required_func = array();
+$required_class = array();
+$required_method = array();
+include(__DIR__."/tests-skipcheck.inc.php");
+--INI--
+date.timezone=America/Los_Angeles
+timecop.func_override=0
+--FILE--
+<?php
+
+echo trim(new \ReflectionFunction('timecop_travel')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_freeze')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_scale')), "\n\n";
+echo trim(new \ReflectionFunction('timecop_return'));
+--EXPECT--
+Function [ <internal:timecop> function timecop_travel ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> DateTimeInterface|int $timestamp ]
+  }
+  - Return [ true ]
+}
+
+Function [ <internal:timecop> function timecop_freeze ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> DateTimeInterface|int $timestamp ]
+  }
+  - Return [ true ]
+}
+
+Function [ <internal:timecop> function timecop_scale ] {
+
+  - Parameters [1] {
+    Parameter #0 [ <required> int $scale ]
+  }
+  - Return [ bool ]
+}
+
+Function [ <internal:timecop> function timecop_return ] {
+
+  - Parameters [0] {
+  }
+  - Return [ true ]
+}

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 {}