Merge branch 'master' into issue4695

Author: oleibman

CHANGELOG.md

@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org). Thia is a
 ### Fixed
 
 - Protected ranges and insert/delete rows/columns. [Issue #4695](https://github.com/PHPOffice/PhpSpreadsheet/issues/4695) [PR #4702](https://github.com/PHPOffice/PhpSpreadsheet/pull/4702)
+- Unexpected Exception in Php DateTime. [Issue #4696](https://github.com/PHPOffice/PhpSpreadsheet/issues/4696) [Issue #917](https://github.com/PHPOffice/PhpSpreadsheet/issues/917) [PR #4697](https://github.com/PHPOffice/PhpSpreadsheet/pull/4697)
 
 ## 2025-10-25 - 5.2.0
 

composer.json

@@ -103,7 +103,7 @@
         "tecnickcom/tcpdf": "^6.5"
     },
     "suggest": {
-        "ext-intl": "PHP Internationalization Functions, regquired for NumberFormat Wizard",
+        "ext-intl": "PHP Internationalization Functions, required for NumberFormat Wizard",
         "mpdf/mpdf": "Option for rendering PDF with PDF Writer",
         "dompdf/dompdf": "Option for rendering PDF with PDF Writer",
         "tecnickcom/tcpdf": "Option for rendering PDF with PDF Writer",

composer.lock

@@ -176,6 +176,7 @@ $columnFilter->createRule()
 In MS Excel, DateGroup filters provide a series of dropdown filter
 selectors for date values, so you can specify entire years, or months
 within a year, or individual days within each month.
+Note that cells covered by such a filter are expected to be in [Excel DateTime Format](./calculation-engine.md#excel-timestamps).
 
 ![04-02-dategroup-autofilter.png](./images/04-02-dategroup-autofilter.png)
 

docs/topics/autofilters.md

@@ -194,20 +194,22 @@ Time functions in Excel will be a PHP `DateTime` object.
 
 #### Excel Timestamps
 
-If `RETURNDATE_EXCEL` is set for the Return Date Type, then the returned
-date value by any access to the Date and Time functions in Excel will be
-a floating point value that represents a number of days from the Excel
-base date. The Excel base date is determined by which calendar Excel
+Excel timestamps are stored as integer or floating point, where the integer portion represents the number of days since a base date,
+and the fraction portion represents the time of day (0 is midnight, 0.5 is noon, 0.999... is just before midnight the next day).
+The Excel base date is determined by which calendar Excel
 uses: the Windows 1900 or the Mac 1904 calendar. 1st January 1900 is the
 base date for the Windows 1900 calendar while 1st January 1904 is the
 base date for the Mac 1904 calendar.
 
-It is possible for scripts to change the calendar used for calculating
-Excel date values by calling the
-`\PhpOffice\PhpSpreadsheet\Shared\Date::setExcelCalendar()` method:
+If `RETURNDATE_EXCEL` is set for the Return Date Type, then the returned
+date value by any access to the Date and Time functions in Excel will be
+a floating point value in Excel timestamp format (previous paragraph).
 
+It is possible for scripts to change the calendar used for calculating
+Excel date values by calling:
 ```php
-\PhpOffice\PhpSpreadsheet\Shared\Date::setExcelCalendar($baseDate);
+\PhpOffice\PhpSpreadsheet\Shared\Date::setExcelCalendar($baseDate); // static property, less preferred
+$spreadsheet->setExcelCalendar($baseDate); // instance property, preferred
 ```
 
 where the following constants can be used for `$baseDate`:
@@ -218,11 +220,10 @@ where the following constants can be used for `$baseDate`:
 The method will return a Boolean True on success, False on failure (e.g.
 if an invalid value is passed in).
 
-The `\PhpOffice\PhpSpreadsheet\Shared\Date::getExcelCalendar()` method can
-be used to determine the current value of this setting:
-
+The current value of this setting can be determined via:
 ```php
-$baseDate = \PhpOffice\PhpSpreadsheet\Shared\Date::getExcelCalendar();
+$baseDate = \PhpOffice\PhpSpreadsheet\Shared\Date::getExcelCalendar(); // static
+$baseDate = $spreadsheet->getExcelCalendar(); // instance
 ```
 
 The default is `CALENDAR_WINDOWS_1900`.

docs/topics/calculation-engine.md

@@ -2581,6 +2581,8 @@ public function extractCellRange(string &$range = 'A1', ?Worksheet $worksheet =
             if (!isset($aReferences[1])) {
                 //    Single cell in range
                 sscanf($aReferences[0], '%[A-Z]%d', $currentCol, $currentRow);
+                /** @var string $currentCol */
+                /** @var int $currentRow */
                 if ($createCell && $worksheet !== null && !$worksheet->cellExists($aReferences[0])) {
                     $worksheet->setCellValue($aReferences[0], null);
                 }
@@ -2600,6 +2602,8 @@ public function extractCellRange(string &$range = 'A1', ?Worksheet $worksheet =
                 foreach ($aReferences as $reference) {
                     // Extract range
                     sscanf($reference, '%[A-Z]%d', $currentCol, $currentRow);
+                    /** @var string $currentCol */
+                    /** @var int $currentRow */
                     if ($createCell && $worksheet !== null && !$worksheet->cellExists($reference)) {
                         $worksheet->setCellValue($reference, null);
                     }

src/PhpSpreadsheet/Calculation/Calculation.php

@@ -7,6 +7,7 @@
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 use PhpOffice\PhpSpreadsheet\Calculation\Information\ExcelError;
 use PhpOffice\PhpSpreadsheet\Shared\Date as SharedDateHelper;
+use Throwable;
 
 class Helpers
 {
@@ -56,6 +57,12 @@ public static function getDateValue(mixed $dateValue, bool $allowBool = true): f
             throw new Exception(ExcelError::NAN());
         }
 
+        try {
+            SharedDateHelper::excelToDateTimeObject((float) $dateValue);
+        } catch (Throwable) {
+            throw new Exception(ExcelError::NAN());
+        }
+
         return (float) $dateValue;
     }
 

src/PhpSpreadsheet/Calculation/DateTimeExcel/Helpers.php

@@ -4,7 +4,9 @@
 
 use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
 use PhpOffice\PhpSpreadsheet\Calculation\Exception;
+use PhpOffice\PhpSpreadsheet\Calculation\Information\ExcelError;
 use PhpOffice\PhpSpreadsheet\Shared\Date as SharedDateHelper;
+use Throwable;
 
 class TimeParts
 {
@@ -44,6 +46,11 @@ public static function hour(mixed $timeValue): array|string|int
         }
 
         // Execute function
+        try {
+            SharedDateHelper::excelToDateTimeObject($timeValue);
+        } catch (Throwable) {
+            return ExcelError::NAN();
+        }
         $timeValue = fmod($timeValue, 1);
         $timeValue = SharedDateHelper::excelToDateTimeObject($timeValue);
         SharedDateHelper::roundMicroseconds($timeValue);
@@ -85,6 +92,11 @@ public static function minute(mixed $timeValue): array|string|int
         }
 
         // Execute function
+        try {
+            SharedDateHelper::excelToDateTimeObject($timeValue);
+        } catch (Throwable) {
+            return ExcelError::NAN();
+        }
         $timeValue = fmod($timeValue, 1);
         $timeValue = SharedDateHelper::excelToDateTimeObject($timeValue);
         SharedDateHelper::roundMicroseconds($timeValue);
@@ -126,6 +138,11 @@ public static function second(mixed $timeValue): array|string|int
         }
 
         // Execute function
+        try {
+            SharedDateHelper::excelToDateTimeObject($timeValue);
+        } catch (Throwable) {
+            return ExcelError::NAN();
+        }
         $timeValue = fmod($timeValue, 1);
         $timeValue = SharedDateHelper::excelToDateTimeObject($timeValue);
         SharedDateHelper::roundMicroseconds($timeValue);

src/PhpSpreadsheet/Calculation/DateTimeExcel/TimeParts.php

@@ -47,8 +47,8 @@ public static function lookup(mixed $lookupValue, mixed $lookupVector, $resultVe
             $lookupVector = array_shift($lookupVector);
         }
 
-        /** @var mixed[] $lookupVector */
-        /** @var mixed[] $resultVector */
+        /** @var array<int, mixed> $lookupVector */
+        /** @var array<int, mixed> $resultVector */
         if ($lookupColumns !== 2) {
             $lookupVector = self::verifyLookupValues($lookupVector, $resultVector);
         }
@@ -57,8 +57,8 @@ public static function lookup(mixed $lookupValue, mixed $lookupVector, $resultVe
     }
 
     /**
-     * @param mixed[] $lookupVector
-     * @param mixed[] $resultVector
+     * @param array<int, mixed> $lookupVector
+     * @param array<int, mixed> $resultVector
      *
      * @return mixed[]
      */
@@ -80,6 +80,7 @@ private static function verifyLookupValues(array $lookupVector, array $resultVec
             if (is_array($dataValue2)) {
                 $dataValue2 = array_shift($dataValue2);
             }
+            /** @var int $key2 */
             $value = [$key1 => $dataValue1, $key2 => $dataValue2];
         }
         unset($value);

src/PhpSpreadsheet/Calculation/LookupRef/Lookup.php

@@ -150,7 +150,7 @@ public static function index(mixed $matrix, mixed $rowNum = 0, mixed $columnNum
 
     /**
      * @param mixed[] $matrix
-     * @param mixed[] $rowKeys
+     * @param array<int, int> $rowKeys
      */
     private static function extractRowValue(array $matrix, array $rowKeys, int $rowNum): mixed
     {
@@ -159,7 +159,7 @@ private static function extractRowValue(array $matrix, array $rowKeys, int $rowN
         }
 
         $rowNum = $rowKeys[--$rowNum];
-        $row = $matrix[$rowNum]; //* @phpstan-ignore-line
+        $row = $matrix[$rowNum];
         if (is_array($row)) {
             return [$rowNum => $row];
         }