Merge pull request #178 from brodos/add-xlsx-options-helpers

Add XLSX option helpers to SimpleExcelReader

Author: Nielsvanpach

README.md

@@ -135,7 +135,7 @@ $rows = SimpleExcelReader::create($pathToXlsx)
 
 If you want to check if a sheet exists, use the `hasSheet()` method.
 
-```php  
+```php
 $hasSheet = SimpleExcelReader::create($pathToXlsx)
     ->hasSheet("sheet1");
 ```
@@ -159,7 +159,7 @@ If your file has headers that are not on the first line, you can use the `header
 to indicate the line at which the headers are present. Any data above this line
 will be discarded from the result.
 
-`headerOnRow` accepts the line number as an argument, starting at 0. Blank lines are not counted. 
+`headerOnRow` accepts the line number as an argument, starting at 0. Blank lines are not counted.
 
 Since blank lines will not be counted, this method is mostly useful for files
 that include formatting above the actual dataset, which can be the case with Excel files.
@@ -291,6 +291,26 @@ $rows = SimpleExcelReader::create($pathToXlsx)
     ->getRows();
 ```
 
+#### Preserve date formatting
+
+By default, when reading a spreadsheet with dates or times, the values are returned as `DateTimeImmutable` objects. To return a formatted date (e.g., “9/20/2024”) instead, use the `preserveDateTimeFormatting` method. The date format will match what’s specified in the spreadsheet.
+
+```php
+$rows = SimpleExcelReader::create($pathToXlsx)
+    ->preserveDateTimeFormatting()
+    ->getRows();
+```
+
+#### Preserve empty rows
+
+You can preserve empty rows by using the `preserveEmptyRows` method.
+
+```php
+$rows = SimpleExcelReader::create($pathToXlsx)
+    ->preserveEmptyRows()
+    ->getRows();
+```
+
 ### Writing files
 
 Here's how you can write a CSV file:
@@ -367,12 +387,12 @@ foreach (range(1, 10_000) as $i) {
         'first_name' => 'John',
         'last_name' => 'Doe',
     ]);
-    
+
     if ($i % 1000 === 0) {
         flush(); // Flush the buffer every 1000 rows
     }
 }
-    
+
 $writer->toBrowser();
 ```
 
@@ -383,7 +403,7 @@ use Spatie\SimpleExcel\SimpleExcelWriter;
 use OpenSpout\Common\Entity\Row;
 
 $writer = SimpleExcelWriter::streamDownload('user-list.xlsx', function ($writerCallback, $downloadName) {
-    
+
     $writerCallback->openToBrowser($downloadName);
 
     $writerCallback->addRow(Row::fromValues([
@@ -467,7 +487,7 @@ $border = new Border(
         new BorderPart(Border::RIGHT, Color::LIGHT_BLUE, Border::WIDTH_THIN, Border::STYLE_SOLID),
         new BorderPart(Border::TOP, Color::LIGHT_BLUE, Border::WIDTH_THIN, Border::STYLE_SOLID)
     );
-    
+
 $style = (new Style())
    ->setFontBold()
    ->setFontSize(15)
@@ -514,14 +534,14 @@ $writer = SimpleExcelWriter::create($pathToXlsx);
 
 Posts::all()->each(function (Post $post) use ($writer) {
     $writer->nameCurrentSheet($post->title);
-    
+
     $post->comments->each(function (Comment $comment) use ($writer) {
         $writer->addRow([
             'comment' => $comment->comment,
             'author' => $comment->author,
         ]);
     });
-    
+
     if(!$post->is($posts->last())) {
         $writer->addNewSheetAndMakeItCurrent();
     }

src/SimpleExcelReader.php

@@ -12,6 +12,8 @@
 use OpenSpout\Reader\ReaderInterface;
 use OpenSpout\Reader\RowIteratorInterface;
 use OpenSpout\Reader\SheetInterface;
+use OpenSpout\Reader\XLSX\Reader as XLSXReader;
+use OpenSpout\Reader\XLSX\Options as XLSXOptions;
 
 class SimpleExcelReader
 {
@@ -33,6 +35,7 @@ class SimpleExcelReader
     protected int $limit = 0;
     protected bool $useLimit = false;
     protected CSVOptions $csvOptions;
+    protected XLSXOptions $xlsxOptions;
 
     public static function create(string $file, string $type = ''): static
     {
@@ -42,6 +45,7 @@ public static function create(string $file, string $type = ''): static
     public function __construct(protected string $path, protected string $type = '')
     {
         $this->csvOptions = new CSVOptions();
+        $this->xlsxOptions = new XLSXOptions();
 
         $this->reader = $this->type ?
             ReaderFactory::createFromType($this->type) :
@@ -52,7 +56,11 @@ public function __construct(protected string $path, protected string $type = '')
 
     protected function setReader(): void
     {
-        $options = $this->reader instanceof CSVReader ? $this->csvOptions : null;
+        $options = match (true) {
+            $this->reader instanceof CSVReader => $this->csvOptions,
+            $this->reader instanceof XLSXReader => $this->xlsxOptions,
+            default => null,
+        };
 
         $this->reader = empty($this->type) ?
             ReaderFactory::createFromFile($this->path, $options) :
@@ -112,6 +120,24 @@ public function useEncoding(string $encoding): self
         return $this;
     }
 
+    public function preserveDateTimeFormatting(): self
+    {
+        if ($this->reader instanceof XLSXReader) {
+            $this->xlsxOptions->SHOULD_FORMAT_DATES = true;
+        }
+
+        return $this;
+    }
+
+    public function preserveEmptyRows(): self
+    {
+        if ($this->reader instanceof XLSXReader) {
+            $this->xlsxOptions->SHOULD_PRESERVE_EMPTY_ROWS = true;
+        }
+
+        return $this;
+    }
+
     public function trimHeaderRow(string $characters = null): self
     {
         $this->trimHeader = true;

tests/SimpleExcelReaderTest.php

@@ -618,3 +618,28 @@ function () {
         ['お名前' => '太郎', 'お名前（フリガナ）' => 'タロウ'],
     ]);
 });
+
+it('can preserve date formatting', function () {
+    $reader = SimpleExcelReader::create(getStubPath('formatted_dates.xlsx'));
+
+    $defaultDates = $reader->getRows()->pluck('created_at')->Toarray();
+
+    expect($defaultDates[0])->toBeInstanceOf(DateTimeImmutable::class);
+    expect($defaultDates[1])->toBeInstanceOf(DateTimeImmutable::class);
+
+    $formattedDates = $reader
+        ->preserveDateTimeFormatting()
+        ->getRows()
+        ->pluck('created_at')
+        ->toArray();
+
+    expect($formattedDates[0])->toEqual('9/20/2024');
+    expect($formattedDates[1])->toEqual('9/19/2024');
+});
+
+it('can preserve empty rows', function () {
+    $reader = SimpleExcelReader::create(getStubPath('empty_rows.xlsx'));
+
+    expect($reader->getRows()->count())->toBe(2);
+    expect($reader->preserveEmptyRows()->getRows()->count())->toBe(3);
+});