Allow Csv Reader to Store Null String in Spreadsheet

docs/topics/reading-and-writing-to-file.md

@@ -449,8 +449,7 @@ $spreadsheet = $reader->loadSpreadsheetFromString($data);
 #### Setting CSV options
 
 Often, CSV files are not really "comma separated", or use semicolon (`;`)
-as a separator. You can instruct
-`\PhpOffice\PhpSpreadsheet\Reader\Csv` some options before reading a CSV
+as a separator. You can set some options before reading a CSV
 file.
 
 The separator will be auto-detected, so in most cases it should not be necessary
@@ -506,6 +505,12 @@ $reader->setSheetIndex(0);
 $spreadsheet = $reader->load('sample.csv');
 ```
 
+The CSV reader will normally not load null strings into the spreadsheet.
+To load them:
+```php
+$reader->setPreserveNullString(true);
+```
+
 Finally, you can set a callback to be invoked when the constructor is executed,
 either through `new Csv()` or `IOFactory::load`,
 and have that callback set the customizable attributes to whatever
@@ -584,8 +589,7 @@ $writer->save("05featuredemo.csv");
 #### Setting CSV options
 
 Often, CSV files are not really "comma separated", or use semicolon (`;`)
-as a separator. You can instruct
-`\PhpOffice\PhpSpreadsheet\Writer\Csv` some options before writing a CSV
+as a separator. You can set some options before writing a CSV
 file:
 
 ```php

src/PhpSpreadsheet/Reader/Csv.php

@@ -103,6 +103,9 @@ class Csv extends BaseReader
      */
     protected $preserveNumericFormatting = false;
 
+    /** @var bool */
+    private $preserveNullString = false;
+
     /**
      * Create a new CSV Reader instance.
      */
@@ -300,9 +303,11 @@ private function openFileOrMemory(string $filename): void
         }
     }
 
-    public function setTestAutoDetect(bool $value): void
+    public function setTestAutoDetect(bool $value): self
     {
         $this->testAutodetect = $value;
+
+        return $this;
     }
 
     private function setAutoDetect(?string $value): ?string
@@ -390,7 +395,7 @@ private function loadStringOrFile(string $filename, Spreadsheet $spreadsheet, bo
             foreach ($rowData as $rowDatum) {
                 $this->convertBoolean($rowDatum, $preserveBooleanString);
                 $numberFormatMask = $this->convertFormattedNumber($rowDatum);
-                if ($rowDatum !== '' && $this->readFilter->readCell($columnLetter, $currentRow)) {
+                if (($rowDatum !== '' || $this->preserveNullString) && $this->readFilter->readCell($columnLetter, $currentRow)) {
                     if ($this->contiguous) {
                         if ($noOutputYet) {
                             $noOutputYet = false;
@@ -625,4 +630,16 @@ public static function guessEncoding(string $filename, string $dflt = self::DEFA
 
         return ($encoding === '') ? $dflt : $encoding;
     }
+
+    public function setPreserveNullString(bool $value): self
+    {
+        $this->preserveNullString = $value;
+
+        return $this;
+    }
+
+    public function getPreserveNullString(): bool
+    {
+        return $this->preserveNullString;
+    }
 }

tests/PhpSpreadsheetTests/Reader/Csv/CsvIssue2840Test.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheetTests\Reader\Csv;
+
+use PhpOffice\PhpSpreadsheet\Reader\Csv;
+use PHPUnit\Framework\TestCase;
+
+class CsvIssue2840Test extends TestCase
+{
+    public function testNullStringIgnore(): void
+    {
+        $reader = new Csv();
+        self::assertFalse($reader->getPreserveNullString());
+        $inputData = <<<EOF
+john,,doe,,
+mary,,jane,,
+EOF;
+        $expected = [
+            ['john', null, 'doe'],
+            ['mary', null, 'jane'],
+        ];
+        $spreadsheet = $reader->loadSpreadsheetFromString($inputData);
+        $sheet = $spreadsheet->getActiveSheet();
+        self::assertSame($expected, $sheet->toArray());
+        $spreadsheet->disconnectWorksheets();
+    }
+
+    public function testNullStringLoad(): void
+    {
+        $reader = new Csv();
+        $reader->setPreserveNullString(true);
+        $inputData = <<<EOF
+john,,doe,,
+mary,,jane,,
+EOF;
+        $expected = [
+            ['john', '', 'doe', '', ''],
+            ['mary', '', 'jane', '', ''],
+        ];
+        $spreadsheet = $reader->loadSpreadsheetFromString($inputData);
+        $sheet = $spreadsheet->getActiveSheet();
+        self::assertSame($expected, $sheet->toArray());
+        $spreadsheet->disconnectWorksheets();
+    }
+}