Add support for reading dates

Author: Alkarex

src/XlsxFastEditor.php

@@ -171,6 +171,67 @@ private function getDomFromPath(string $path): \DOMDocument
 		return $this->getXPathFromPath($path)->document;
 	}
 
+	/**
+	 * Excel can either use a base date from year 1900 (Microsoft Windows) or from year 1904 (old Apple MacOS).
+	 * https://support.microsoft.com/en-us/office/date-systems-in-excel-e7fe7167-48a9-4b96-bb53-5612a800b487
+	 * @phpstan-return 1900|1904
+	 */
+	public function getWorkbookDateSystem(): int
+	{
+		static $baseYear = 0;
+		if ($baseYear == 0) {
+			$xpath = $this->getXPathFromPath(self::WORKBOOK_PATH);
+			$date1904 = $xpath->evaluate('normalize-space(/o:workbook/o:workbookPr/@date1904)');
+			if (is_string($date1904) && in_array(strtolower(trim($date1904)), ['true', '1'], true)) {
+				$baseYear = 1904;
+			} else {
+				$baseYear = 1900;
+			}
+		}
+		return $baseYear;
+	}
+
+	public static function excelDateToDateTime(float $excelDateTime, int $workbookDateSystem = 1900): \DateTimeImmutable
+	{
+		static $baseDate1900 = null;
+		static $baseDate1904 = null;
+		if ($workbookDateSystem === 1900) {
+			if ($excelDateTime < 1) {
+				// Make cells with only time (no date) to start on 1900-01-01
+				$excelDateTime++;
+			}
+			if ($excelDateTime < 60) {
+				// https://learn.microsoft.com/en-us/office/troubleshoot/excel/wrongly-assumes-1900-is-leap-year
+				$excelDateTime++;
+			}
+			// 1 January 1900 as serial number 1 in the 1900 Date System, accounting for leap year problem
+			if ($baseDate1900 === null) {
+				$baseDate1900 = new \DateTimeImmutable('1899-12-30');
+			}
+			$excelBaseDate = $baseDate1900;
+		} elseif ($workbookDateSystem === 1904) {
+			// 1 January 1904 as serial number 0 in the 1904 Date System
+			if ($baseDate1904 === null) {
+				$baseDate1904 = new \DateTimeImmutable('1904-01-01');
+			}
+			$excelBaseDate = $baseDate1904;
+		} else {
+			throw new \InvalidArgumentException('Invalid Excel workbook date system! Supported values: 1900, 1904');
+		}
+
+		$daysOffset = floor($excelDateTime);
+		$iso8601 = "P{$daysOffset}D";
+
+		$timeFraction = $excelDateTime - $daysOffset;
+		if ($timeFraction > 0) {
+			// Convert days to seconds with no more than milliseconds precision
+			$seconds = floor($timeFraction * 86400000) / 1000;
+			$iso8601 .= "T{$seconds}S";
+		}
+
+		return $excelBaseDate->add(new \DateInterval($iso8601));
+	}
+
 	/**
 	 * Count the number of worksheets in the workbook.
 	 */
@@ -532,6 +593,18 @@ public function readFloat(int $sheetNumber, string $cellName): ?float
 		return $cell === null ? null : $cell->readFloat();
 	}
 
+	/**
+	 * Read a date/time in the given worksheet at the given cell location.
+	 *
+	 * @param int $sheetNumber Worksheet number (base 1)
+	 * @param $cellName Cell name such as `B4`
+	 */
+	public function readDate(int $sheetNumber, string $cellName): ?\DateTimeImmutable
+	{
+		$cell = $this->getCell($sheetNumber, $cellName, XlsxFastEditor::ACCESS_MODE_NULL);
+		return $cell === null ? null : $cell->readDateTime();
+	}
+
 	/**
 	 * Read an integer in the given worksheet at the given cell location.
 	 *

src/XlsxFastEditorCell.php

@@ -139,6 +139,18 @@ public function readFloat(): ?float
 		return (float)$value;
 	}
 
+	/**
+	 * Read the date/time value of the cell, if any.
+	 */
+	public function readDateTime(): ?\DateTimeImmutable
+	{
+		$value = $this->readFloat();
+		if ($value === null) {
+			return null;
+		}
+		return XlsxFastEditor::excelDateToDateTime($value, $this->editor->getWorkbookDateSystem());
+	}
+
 	/**
 	 * Read the integer value of the cell.
 	 */

tests/test.php

@@ -17,6 +17,11 @@
 
 	assert($xlsxFastEditor->getWorksheetCount() === 2);
 
+	assert($xlsxFastEditor->getWorkbookDateSystem() === 1900);
+	assert(XlsxFastEditor::excelDateToDateTime(0.5, 1900)->format('c') === '1900-01-01T12:00:00+01:00');
+	assert(XlsxFastEditor::excelDateToDateTime(32, 1900)->format('c') === '1900-02-01T00:00:00+01:00');
+	assert(XlsxFastEditor::excelDateToDateTime(44865, 1904)->format('c') === '2026-11-01T00:00:00+01:00');
+
 	$sheet1 = $xlsxFastEditor->getWorksheetNumber('Sheet1');
 	assert($sheet1 === 1);
 
@@ -42,14 +47,18 @@
 	assert($xlsxFastEditor->readInt($sheet2, 'c3') === -5 * 2);
 	assert($xlsxFastEditor->readString($sheet2, 'B3') === 'déjà-vu');
 
+	assert($xlsxFastEditor->readDate($sheet1, 'F2')?->format('c') === '1980-11-24T00:00:00+01:00');
+	assert($xlsxFastEditor->readDate($sheet1, 'F3')?->format('c') === '1980-11-24T10:20:30+01:00');
+	assert($xlsxFastEditor->readDate($sheet1, 'F4')?->format('c') === '1900-01-01T10:20:30+01:00');
+
 	assert($xlsxFastEditor->readArray($sheet1)['B'][2] === 'Hello');
 	assert($xlsxFastEditor->readArrayWithHeaders($sheet1)['Strings'][2] === 'Hello');
 
 	// Navigation
 	assert($xlsxFastEditor->getFirstRow($sheet1)?->number() === 1);
 	assert($xlsxFastEditor->getRow($sheet1, 1)?->getFirstCell()?->name() === 'A1');
 	assert($xlsxFastEditor->getRow($sheet1, 2)?->number() === 2);
-	assert($xlsxFastEditor->getRow($sheet1, 3)?->getLastCell()?->name() === 'E3');
+	assert($xlsxFastEditor->getRow($sheet1, 3)?->getLastCell()?->name() === 'F3');
 	assert($xlsxFastEditor->getRow($sheet1, 4)?->getCell('D4')?->name() === 'D4');
 	assert($xlsxFastEditor->getLastRow($sheet1)?->number() === 4);
 
@@ -70,7 +79,7 @@
 			$nb++;
 		}
 	}
-	assert($nb === 20);
+	assert($nb === 24);
 
 	// Writing existing cells
 	$xlsxFastEditor->writeFormula($sheet1, 'c2', '=2*3');