Better Typing in Test Members

Change "mixed" declarations to more accurate types in test members; in particular, change those that would be flagged if we were to run Phpstan at level 9 (we currently run level 8). I may or may not follow up with source code (over 700 level-9 problems remain for src), but, as with strict typing, there is no reason to avoid the effort for test members.

It was necessary to update some doc blocks in src to accommodate this change. However, no executable code is touched.

Author: oleibman

.php-cs-fixer.dist.php

@@ -3,7 +3,7 @@
 $finder = PhpCsFixer\Finder::create()
     ->exclude('vendor')
     ->notPath('src/PhpSpreadsheet/Writer/ZipStream3.php')
-    ->name('/(\.php|^generate-document|^generate-locales)$/')
+    ->name('/(\.php|^generate-document|^generate-locales|^check-phpdoc-types)$/')
     ->in(__DIR__);
 
 $config = new PhpCsFixer\Config();

.phpcs.xml.dist

@@ -8,6 +8,7 @@
     <file>infra</file>
     <file>bin/generate-document</file>
     <file>bin/generate-locales</file>
+    <file>bin/check-phpdoc-types</file>
 
     <exclude-pattern>samples/Header.php</exclude-pattern>
     <exclude-pattern>*/tests/Core/*/*Test\.(inc|css|js)$</exclude-pattern>

bin/check-phpdoc-types

@@ -10,9 +10,9 @@
  */
 function checkPhpDocTypes(): void
 {
-    $content = `git diff --cached` ?? `git diff` ?? `git show HEAD`;
-    preg_match_all('~^\+ +\* @(param|var) (mixed|string|int|float|bool|null|array|\?|\|)+( \$\w+)?$~m', $content, $parameters);
-    preg_match_all('~^\+ +\* @return (mixed|string|int|float|bool|null|array|void|\?|\|)+$~m', $content, $returns);
+    $content = shell_exec('git diff --cached') ?? shell_exec('git diff') ?? shell_exec('git show HEAD');
+    preg_match_all('~^\+ +\* @(param|var) (mixed|string|int|float|bool|null|array|\?|\|)+( \$\w+)?$~m', "$content", $parameters);
+    preg_match_all('~^\+ +\* @return (mixed|string|int|float|bool|null|array|void|\?|\|)+$~m', "$content", $returns);
 
     $errors = [
         ...$parameters[0],
@@ -21,7 +21,7 @@ function checkPhpDocTypes(): void
 
     if ($errors) {
         echo 'PHP native types must be used instead of PHPDoc types (without comments), for the following lines:' . PHP_EOL . PHP_EOL;
-        echo join(PHP_EOL, $errors) . PHP_EOL;
+        echo implode(PHP_EOL, $errors) . PHP_EOL;
         exit(1);
     }
 }

phpstan.neon.dist

@@ -12,6 +12,7 @@ parameters:
         - infra/
         - bin/generate-document
         - bin/generate-locales
+        - bin/check-phpdoc-types
     excludePaths:
         - src/PhpSpreadsheet/Chart/Renderer/JpGraph.php
         - src/PhpSpreadsheet/Chart/Renderer/JpGraphRendererBase.php

src/PhpSpreadsheet/Calculation/DateTimeExcel/Date.php

@@ -27,7 +27,7 @@ class Date
      * A Month name or abbreviation (English only at this point) such as 'January' or 'Jan' will still be accepted,
      *     as will a day value with a suffix (e.g. '21st' rather than simply 21); again only English language.
      *
-     * @param array|int|string $year The value of the year argument can include one to four digits.
+     * @param array|float|int|string $year The value of the year argument can include one to four digits.
      *                                Excel interprets the year argument according to the configured
      *                                date system: 1900 or 1904.
      *                                If year is between 0 (zero) and 1899 (inclusive), Excel adds that
@@ -63,7 +63,7 @@ class Date
      *         If an array of numbers is passed as the argument, then the returned result will also be an array
      *            with the same dimensions
      */
-    public static function fromYMD(array|int|string $year, array|float|int|string $month, array|float|int|string $day): mixed
+    public static function fromYMD(array|float|int|string $year, array|float|int|string $month, array|float|int|string $day): mixed
     {
         if (is_array($year) || is_array($month) || is_array($day)) {
             return self::evaluateArrayArguments([self::class, __FUNCTION__], $year, $month, $day);

src/PhpSpreadsheet/Calculation/DateTimeExcel/DateValue.php

@@ -24,7 +24,7 @@ class DateValue
      * Excel Function:
      *        DATEVALUE(dateValue)
      *
-     * @param null|array|int|string $dateValue Text that represents a date in a Microsoft Excel date format.
+     * @param null|array|bool|float|int|string $dateValue Text that represents a date in a Microsoft Excel date format.
      *                                    For example, "1/30/2008" or "30-Jan-2008" are text strings within
      *                                    quotation marks that represent dates. Using the default date
      *                                    system in Excel for Windows, date_text must represent a date from
@@ -39,7 +39,7 @@ class DateValue
      *         If an array of numbers is passed as the argument, then the returned result will also be an array
      *            with the same dimensions
      */
-    public static function fromString(null|array|string|int|bool $dateValue): mixed
+    public static function fromString(null|array|string|int|bool|float $dateValue): mixed
     {
         if (is_array($dateValue)) {
             return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $dateValue);

src/PhpSpreadsheet/Calculation/DateTimeExcel/TimeValue.php

@@ -25,7 +25,7 @@ class TimeValue
      * Excel Function:
      *        TIMEVALUE(timeValue)
      *
-     * @param null|array|string $timeValue A text string that represents a time in any one of the Microsoft
+     * @param null|array|bool|int|string $timeValue A text string that represents a time in any one of the Microsoft
      *                                    Excel time formats; for example, "6:45 PM" and "18:45" text strings
      *                                    within quotation marks that represent time.
      *                                    Date information in time_text is ignored.

src/PhpSpreadsheet/Calculation/DateTimeExcel/Week.php

@@ -137,7 +137,7 @@ public static function isoWeekNumber(mixed $dateValue): array|int|string
      * Excel Function:
      *        WEEKDAY(dateValue[,style])
      *
-     * @param null|array|float|int|string $dateValue Excel date serial value (float), PHP date timestamp (integer),
+     * @param null|array|bool|float|int|string $dateValue Excel date serial value (float), PHP date timestamp (integer),
      *                                    PHP DateTime object, or a standard date string
      *                         Or can be an array of date values
      * @param mixed $style A number that determines the type of return value

src/PhpSpreadsheet/Calculation/Engineering/Compare.php

@@ -20,16 +20,16 @@ class Compare
      *        functions you calculate the count of equal pairs. This function is also known as the
      *        Kronecker Delta function.
      *
-     * @param array|float $a the first number
+     * @param array|bool|float|int|string $a the first number
      *                      Or can be an array of values
-     * @param array|float $b The second number. If omitted, b is assumed to be zero.
+     * @param array|bool|float|int|string $b The second number. If omitted, b is assumed to be zero.
      *                      Or can be an array of values
      *
      * @return array|int|string (string in the event of an error)
      *         If an array of numbers is passed as an argument, then the returned result will also be an array
      *            with the same dimensions
      */
-    public static function DELTA(array|float|bool|string $a, array|float|bool|string $b = 0.0): array|string|int
+    public static function DELTA(array|float|bool|string|int $a, array|float|bool|string|int $b = 0.0): array|string|int
     {
         if (is_array($a) || is_array($b)) {
             return self::evaluateArrayArguments([self::class, __FUNCTION__], $a, $b);
@@ -55,16 +55,16 @@ public static function DELTA(array|float|bool|string $a, array|float|bool|string
      *    Use this function to filter a set of values. For example, by summing several GESTEP
      *        functions you calculate the count of values that exceed a threshold.
      *
-     * @param array|float $number the value to test against step
+     * @param array|bool|float|int|string $number the value to test against step
      *                      Or can be an array of values
-     * @param null|array|float $step The threshold value. If you omit a value for step, GESTEP uses zero.
+     * @param null|array|bool|float|int|string $step The threshold value. If you omit a value for step, GESTEP uses zero.
      *                      Or can be an array of values
      *
      * @return array|int|string (string in the event of an error)
      *         If an array of numbers is passed as an argument, then the returned result will also be an array
      *            with the same dimensions
      */
-    public static function GESTEP(array|float|bool|string $number, $step = 0.0): array|string|int
+    public static function GESTEP(array|float|bool|string|int $number, $step = 0.0): array|string|int
     {
         if (is_array($number) || is_array($step)) {
             return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $step);

src/PhpSpreadsheet/Calculation/Engineering/ConvertBinary.php

@@ -15,7 +15,7 @@ class ConvertBinary extends ConvertBase
      * Excel Function:
      *        BIN2DEC(x)
      *
-     * @param array|string $value The binary number (as a string) that you want to convert. The number
+     * @param array|bool|float|int|string $value The binary number (as a string) that you want to convert. The number
      *                                cannot contain more than 10 characters (10 bits). The most significant
      *                                bit of number is the sign bit. The remaining 9 bits are magnitude bits.
      *                                Negative numbers are represented using two's-complement notation.
@@ -58,14 +58,14 @@ public static function toDecimal($value)
      * Excel Function:
      *        BIN2HEX(x[,places])
      *
-     * @param array|string $value The binary number (as a string) that you want to convert. The number
+     * @param array|bool|float|int|string $value The binary number (as a string) that you want to convert. The number
      *                                cannot contain more than 10 characters (10 bits). The most significant
      *                                bit of number is the sign bit. The remaining 9 bits are magnitude bits.
      *                                Negative numbers are represented using two's-complement notation.
      *                                If number is not a valid binary number, or if number contains more than
      *                                10 characters (10 bits), BIN2HEX returns the #NUM! error value.
      *                      Or can be an array of values
-     * @param array|int $places The number of characters to use. If places is omitted, BIN2HEX uses the
+     * @param null|array|float|int|string $places The number of characters to use. If places is omitted, BIN2HEX uses the
      *                                minimum number of characters necessary. Places is useful for padding the
      *                                return value with leading 0s (zeros).
      *                                If places is not an integer, it is truncated.
@@ -111,14 +111,14 @@ public static function toHex($value, $places = null): array|string
      * Excel Function:
      *        BIN2OCT(x[,places])
      *
-     * @param array|string $value The binary number (as a string) that you want to convert. The number
+     * @param array|bool|float|int|string $value The binary number (as a string) that you want to convert. The number
      *                                cannot contain more than 10 characters (10 bits). The most significant
      *                                bit of number is the sign bit. The remaining 9 bits are magnitude bits.
      *                                Negative numbers are represented using two's-complement notation.
      *                                If number is not a valid binary number, or if number contains more than
      *                                10 characters (10 bits), BIN2OCT returns the #NUM! error value.
      *                      Or can be an array of values
-     * @param array|int $places The number of characters to use. If places is omitted, BIN2OCT uses the
+     * @param null|array|float|int|string $places The number of characters to use. If places is omitted, BIN2OCT uses the
      *                                minimum number of characters necessary. Places is useful for padding the
      *                                return value with leading 0s (zeros).
      *                                If places is not an integer, it is truncated.