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.

.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.

src/PhpSpreadsheet/Calculation/Engineering/ConvertDecimal.php

@@ -22,7 +22,7 @@ class ConvertDecimal extends ConvertBase
      * Excel Function:
      *        DEC2BIN(x[,places])
      *
-     * @param array|string $value The decimal integer you want to convert. If number is negative,
+     * @param array|bool|float|int|string $value The decimal integer you want to convert. If number is negative,
      *                          valid place values are ignored and DEC2BIN returns a 10-character
      *                          (10-bit) binary number in which the most significant bit is the sign
      *                          bit. The remaining 9 bits are magnitude bits. Negative numbers are
@@ -33,7 +33,7 @@ class ConvertDecimal extends ConvertBase
      *                      If DEC2BIN requires more than places characters, it 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, DEC2BIN uses
+     * @param null|array|float|int|string $places The number of characters to use. If places is omitted, DEC2BIN 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.
@@ -79,7 +79,7 @@ public static function toBinary($value, $places = null): array|string
      * Excel Function:
      *        DEC2HEX(x[,places])
      *
-     * @param array|string $value The decimal integer you want to convert. If number is negative,
+     * @param array|bool|float|int|string $value The decimal integer you want to convert. If number is negative,
      *                          places is ignored and DEC2HEX returns a 10-character (40-bit)
      *                          hexadecimal number in which the most significant bit is the sign
      *                          bit. The remaining 39 bits are magnitude bits. Negative numbers
@@ -90,7 +90,7 @@ public static function toBinary($value, $places = null): array|string
      *                      If DEC2HEX requires more than places characters, it 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, DEC2HEX uses
+     * @param null|array|float|int|string $places The number of characters to use. If places is omitted, DEC2HEX 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.
@@ -155,7 +155,7 @@ public static function hex32bit(float $value, string $hexstr, bool $force = fals
      * Excel Function:
      *        DEC2OCT(x[,places])
      *
-     * @param array|string $value The decimal integer you want to convert. If number is negative,
+     * @param array|bool|float|int|string $value The decimal integer you want to convert. If number is negative,
      *                          places is ignored and DEC2OCT returns a 10-character (30-bit)
      *                          octal number in which the most significant bit is the sign bit.
      *                          The remaining 29 bits are magnitude bits. Negative numbers are

src/PhpSpreadsheet/Calculation/Engineering/ConvertHex.php

@@ -15,7 +15,7 @@ class ConvertHex extends ConvertBase
      * Excel Function:
      *        HEX2BIN(x[,places])
      *
-     * @param array|string $value The hexadecimal number you want to convert.
+     * @param array|bool|float|string $value The hexadecimal number you want to convert.
      *                      Number cannot contain more than 10 characters.
      *                      The most significant bit of number is the sign bit (40th bit from the right).
      *                      The remaining 9 bits are magnitude bits.
@@ -65,7 +65,7 @@ public static function toBinary($value, $places = null): array|string
      * Excel Function:
      *        HEX2DEC(x)
      *
-     * @param array|string $value The hexadecimal number you want to convert. This number cannot
+     * @param array|bool|float|int|string $value The hexadecimal number you want to convert. This number cannot
      *                          contain more than 10 characters (40 bits). The most significant
      *                          bit of number is the sign bit. The remaining 39 bits are magnitude
      *                          bits. Negative numbers are represented using two's-complement
@@ -118,7 +118,7 @@ public static function toDecimal($value)
      * Excel Function:
      *        HEX2OCT(x[,places])
      *
-     * @param array|string $value The hexadecimal number you want to convert. Number cannot
+     * @param array|bool|float|int|string $value The hexadecimal number you want to convert. Number cannot
      *                                    contain more than 10 characters. The most significant bit of
      *                                    number is the sign bit. The remaining 39 bits are magnitude
      *                                    bits. Negative numbers are represented using two's-complement

src/PhpSpreadsheet/Calculation/Engineering/ConvertOctal.php

@@ -15,7 +15,7 @@ class ConvertOctal extends ConvertBase
      * Excel Function:
      *        OCT2BIN(x[,places])
      *
-     * @param array|string $value The octal number you want to convert. Number may not
+     * @param array|bool|float|int|string $value The octal number you want to convert. Number may not
      *                          contain more than 10 characters. The most significant
      *                          bit of number is the sign bit. The remaining 29 bits
      *                          are magnitude bits. Negative numbers are represented
@@ -69,7 +69,7 @@ public static function toBinary($value, $places = null): array|string
      * Excel Function:
      *        OCT2DEC(x)
      *
-     * @param array|string $value The octal number you want to convert. Number may not contain
+     * @param array|bool|float|int|string $value The octal number you want to convert. Number may not contain
      *                          more than 10 octal characters (30 bits). The most significant
      *                          bit of number is the sign bit. The remaining 29 bits are
      *                          magnitude bits. Negative numbers are represented using
@@ -118,7 +118,7 @@ public static function toDecimal($value)
      * Excel Function:
      *        OCT2HEX(x[,places])
      *
-     * @param array|string $value The octal number you want to convert. Number may not contain
+     * @param array|bool|float|int|string $value The octal number you want to convert. Number may not contain
      *                          more than 10 octal characters (30 bits). The most significant
      *                          bit of number is the sign bit. The remaining 29 bits are
      *                          magnitude bits. Negative numbers are represented using

src/PhpSpreadsheet/Shared/Font.php

@@ -499,11 +499,11 @@ public static function getTextWidthPixelsApprox(string $columnText, FontStyle $f
     /**
      * Calculate an (approximate) pixel size, based on a font points size.
      *
-     * @param int $fontSizeInPoints Font size (in points)
+     * @param float|int $fontSizeInPoints Font size (in points)
      *
      * @return int Font size (in pixels)
      */
-    public static function fontSizeToPixels(int $fontSizeInPoints): int
+    public static function fontSizeToPixels(float|int $fontSizeInPoints): int
     {
         return (int) ((4 / 3) * $fontSizeInPoints);
     }