A Win For Scrutinizer!

It flagged a statement as dead code. It was correct - there was a typo in the variable name. But no tests had failed. The explanation was, of course, that this particular path was not adequately tested.

PhpSpreadsheet extends Excel (dating back to PHPExcel) by allowing the ordinal form of days in the DATE function, implemented as "take the numeric portion if the field is a string consisting of a numeric portion followed by some alphabetics". Whether or not this is a good idea, it would be a breaking change to eliminate it, so that's not going to happen. However, the same logic has been applied to month, and I don't see a use case for that, so I'm eliminating it - any non-numeric string used as the month parameter will now result in a VALUE error. It also turns out that Excel accepts null, false, and true for the month, and PhpSpreadsheet will now do likewise.

Author: oleibman

CHANGELOG.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 - Start migration to Phpstan level 9. [PR #4396](https://github.com/PHPOffice/PhpSpreadsheet/pull/4396)
 - Calculation locale logic moved to separate class. [PR #4398](https://github.com/PHPOffice/PhpSpreadsheet/pull/4398)
 - TREND_POLYNOMIAL_* and TREND_BEST_FIT do not work, and are changed to throw Exceptions if attempted. (TREND_BEST_FIT_NO_POLY works.) An attempt to use an unknown trend type will now also throw an exception. [Issue #4400](https://github.com/PHPOffice/PhpSpreadsheet/issues/4400) [PR #4339](https://github.com/PHPOffice/PhpSpreadsheet/pull/4339)
+- Month parameter of DATE function will now return VALUE if an ordinal string (e.g. '3rd') is used, but will accept bool or null. [PR #4420](https://github.com/PHPOffice/PhpSpreadsheet/pull/4420)
 
 ### Moved
 

src/PhpSpreadsheet/Calculation/DateTimeExcel/Date.php

@@ -64,7 +64,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|float|int|string $year, array|float|int|string $month, array|float|int|string $day): float|int|DateTime|string|array
+    public static function fromYMD(array|float|int|string $year, null|array|bool|float|int|string $month, array|float|int|string $day): float|int|DateTime|string|array
     {
         if (is_array($year) || is_array($month) || is_array($day)) {
             return self::evaluateArrayArguments([self::class, __FUNCTION__], $year, $month, $day);
@@ -121,13 +121,14 @@ private static function getYear(mixed $year, int $baseYear): int
      */
     private static function getMonth(mixed $month): int
     {
-        if (is_string($month) && !is_numeric($month)) {
-            $month = SharedDateHelper::monthStringToNumber($month);
-        }
-        if ($month === null) {
+        if (is_string($month)) {
+            if (!is_numeric($month)) {
+                $month = SharedDateHelper::monthStringToNumber($month);
+            }
+        } elseif ($month === null) {
             $month = 0;
-        } elseif (is_scalar($month)) {
-            $year = StringHelper::testStringAsNumeric((string) $month);
+        } elseif (is_bool($month)) {
+            $month = (int) $month;
         }
         if (!is_numeric($month)) {
             throw new Exception(ExcelError::VALUE());

tests/PhpSpreadsheetTests/Calculation/Functions/DateTime/DateTest.php

@@ -12,6 +12,7 @@
 use PhpOffice\PhpSpreadsheet\Shared\Date as SharedDate;
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
 use PhpOffice\PhpSpreadsheetTests\Calculation\Functions\FormulaArguments;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
 class DateTest extends TestCase
@@ -36,14 +37,14 @@ protected function tearDown(): void
         Functions::setReturnDateType($this->returnDateType);
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerDATE')]
-    public function testDirectCallToDATE(float|string $expectedResult, int|string $year, float|int|string $month, float|int|string $day): void
+    #[DataProvider('providerDATE')]
+    public function testDirectCallToDATE(float|string $expectedResult, int|string $year, null|bool|float|int|string $month, float|int|string $day): void
     {
         $result = Date::fromYMD($year, $month, $day);
         self::assertSame($expectedResult, $result);
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerDATE')]
+    #[DataProvider('providerDATE')]
     public function testDATEAsFormula(mixed $expectedResult, mixed ...$args): void
     {
         $arguments = new FormulaArguments(...$args);
@@ -55,7 +56,7 @@ public function testDATEAsFormula(mixed $expectedResult, mixed ...$args): void
         self::assertSame($expectedResult, $result);
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerDATE')]
+    #[DataProvider('providerDATE')]
     public function testDATEInWorksheet(mixed $expectedResult, mixed ...$args): void
     {
         $arguments = new FormulaArguments(...$args);
@@ -78,7 +79,7 @@ public static function providerDATE(): array
         return require 'tests/data/Calculation/DateTime/DATE.php';
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerUnhappyDATE')]
+    #[DataProvider('providerUnhappyDATE')]
     public function testDATEUnhappyPath(string $expectedException, mixed ...$args): void
     {
         $arguments = new FormulaArguments(...$args);
@@ -136,7 +137,7 @@ public function testDATEWith1904Calendar(): void
         self::assertEquals($result, ExcelError::NAN());
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerDateArray')]
+    #[DataProvider('providerDateArray')]
     public function testDateArray(array $expectedResult, string $year, string $month, string $day): void
     {
         $calculation = Calculation::getInstance();
@@ -200,7 +201,7 @@ public static function providerDateArray(): array
         ];
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerDateArrayException')]
+    #[DataProvider('providerDateArrayException')]
     public function testDateArrayException(string $year, string $month, string $day): void
     {
         $calculation = Calculation::getInstance();

tests/data/Calculation/DateTime/DATE.php

@@ -62,11 +62,14 @@
     [39844.0, 2008, 13, 31],
     [39813.0, 2009, 1, 0],
     [39812.0, 2009, 1, -1],
+    'month expressed as true' => [39812.0, 2009, true, -1],
     [39782.0, 2009, 0, 0],
     [39781.0, 2009, 0, -1],
     [39752.0, 2009, -1, 0],
     [39751.0, 2009, -1, -1],
     [40146.0, 2010, 0, -1],
+    'month expressed as false' => [40146.0, 2010, false, -1],
+    'month expressed as null' => [40146.0, 2010, null, -1],
     [40329.0, 2010, 5, 31],
     [40199.0, 2010, 1, '21st'], // Excel can't parse ordinal, PhpSpreadsheet can
     [40200.0, 2010, 1, '22nd'], // Excel can't parse ordinal, PhpSpreadsheet can
@@ -75,6 +78,8 @@
     [40258.0, 2010, 'March', '21st'], // ordinal and month name
     // MS Excel will fail with a #VALUE return, but PhpSpreadsheet can parse this date
     [40258.0, 2010, 'March', 21], // Excel can't parse month name, PhpSpreadsheet can
+    'month expressed as string' => [40258.0, 2010, '03', 21],
+    'month expressed as invalid string' => [ExcelError::VALUE(), 2010, '03x', 21],
     [ExcelError::VALUE(), 'ABC', 1, 21],
     [ExcelError::VALUE(), 2010, 'DEF', 21],
     [ExcelError::VALUE(), 2010, 3, 'GHI'],