Merge pull request #3314 from PHPOffice/CellIterator-Option-to-create-new-cell-or-return-null

Provide an option for Cell Iterators to return a null or create a new cell when cell doesn't exist

Author: MarkBaker

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
+- Option for Cell Iterator to return a null value or create and return a new cell when accessing a cell that doesn't exist [PR #3314](https://github.com/PHPOffice/PhpSpreadsheet/pull/3314)
 - Support for Structured References in the Calculation Engine [PR #3261](https://github.com/PHPOffice/PhpSpreadsheet/pull/3261)
 - Limited Support for Form Controls [PR #3130](https://github.com/PHPOffice/PhpSpreadsheet/pull/3130) [Issue #2396](https://github.com/PHPOffice/PhpSpreadsheet/issues/2396) [Issue #1770](https://github.com/PHPOffice/PhpSpreadsheet/issues/1770) [Issue #2388](https://github.com/PHPOffice/PhpSpreadsheet/issues/2388) [Issue #2904](https://github.com/PHPOffice/PhpSpreadsheet/issues/2904) [Issue #2661](https://github.com/PHPOffice/PhpSpreadsheet/issues/2661)
 

docs/topics/accessing-cells.md

@@ -46,10 +46,10 @@ particularly when working with large spreadsheets. One technique used to
 reduce this memory overhead is cell caching, so cells are actually
 maintained in a collection that may or may not be held in memory while you
 are working with the spreadsheet. Because of this, a call to `getCell()`
-(or any similar method) returns the cell data, and a pointer to the collection.
+(or any similar method) returns the cell data, and sets a cell pointer to that cell in the collection.
 While this is not normally an issue, it can become significant
 if you assign the result of a call to `getCell()` to a variable. Any
-subsequent calls to retrieve other cells will unset that pointer, although
+subsequent calls to retrieve other cells will change that pointer, although
 the cell object will still retain its data values.
 
 What does this mean? Consider the following code:
@@ -441,16 +441,25 @@ foreach ($worksheet->getRowIterator() as $row) {
 echo '</table>' . PHP_EOL;
 ```
 
-Note that we have set the cell iterator's
-`setIterateOnlyExistingCells()` to FALSE. This makes the iterator loop
-all cells within the worksheet range, even if they have not been set.
-
-The cell iterator will return a `null` as the cell value if it is not
-set in the worksheet. Setting the cell iterator's
-`setIterateOnlyExistingCells()` to `false` will loop all cells in the
-worksheet that can be available at that moment. This will create new
-cells if required and increase memory usage! Only use it if it is
-intended to loop all cells that are possibly available.
+Note that we have set the cell iterator's `setIterateOnlyExistingCells()`
+to FALSE. This makes the iterator loop all cells within the worksheet
+range, even if they have not been set.
+
+The cell iterator will create a new empty cell in the worksheet if it
+doesn't exist; return a `null` as the cell value if it is not set in
+the worksheet; although we can also tell it to return a null value
+rather than returning a new empty cell.
+Setting the cell iterator's `setIterateOnlyExistingCells()` to `false`
+will loop all cells in the worksheet that can be available at that
+moment. If this is then set to create new cells if required, then it
+will likely increase memory usage!
+Only use it if it is intended to loop all cells that are possibly
+available; otherwise use the option to return a null value if a cell
+doesn't exist, or iterate only the cells that already exist.
+
+It is also possible to call the Row object's `isEmpty()` method to
+determine whether you need to instantiate the Cell Iterator for that
+Row.
 
 ### Looping through cells using indexes
 

src/PhpSpreadsheet/Worksheet/CellIterator.php

@@ -17,6 +17,10 @@ abstract class CellIterator implements NativeIterator
 
     public const TREAT_EMPTY_STRING_AS_EMPTY_CELL = 2;
 
+    public const IF_NOT_EXISTS_RETURN_NULL = false;
+
+    public const IF_NOT_EXISTS_CREATE_NEW = true;
+
     /**
      * Worksheet to iterate.
      *
@@ -38,6 +42,14 @@ abstract class CellIterator implements NativeIterator
      */
     protected $onlyExistingCells = false;
 
+    /**
+     * If iterating all cells, and a cell doesn't exist, identifies whether a new cell should be created,
+     *    or if the iterator should return a null value.
+     *
+     * @var bool
+     */
+    protected $ifNotExists = self::IF_NOT_EXISTS_CREATE_NEW;
+
     /**
      * Destructor.
      */
@@ -47,6 +59,16 @@ public function __destruct()
         $this->worksheet = $this->cellCollection = null;
     }
 
+    public function getIfNotExists(): bool
+    {
+        return $this->ifNotExists;
+    }
+
+    public function setIfNotExists(bool $ifNotExists = self::IF_NOT_EXISTS_CREATE_NEW): void
+    {
+        $this->ifNotExists = $ifNotExists;
+    }
+
     /**
      * Get loop only existing cells.
      */

src/PhpSpreadsheet/Worksheet/ColumnCellIterator.php

@@ -128,7 +128,11 @@ public function current(): ?Cell
 
         return $this->cellCollection->has($cellAddress)
             ? $this->cellCollection->get($cellAddress)
-            : $this->worksheet->createNewCell($cellAddress);
+            : (
+                $this->ifNotExists === self::IF_NOT_EXISTS_CREATE_NEW
+                ? $this->worksheet->createNewCell($cellAddress)
+                : null
+            );
     }
 
     /**

src/PhpSpreadsheet/Worksheet/RowCellIterator.php

@@ -127,7 +127,11 @@ public function current(): ?Cell
 
         return $this->cellCollection->has($cellAddress)
             ? $this->cellCollection->get($cellAddress)
-            : $this->worksheet->createNewCell($cellAddress);
+            : (
+                $this->ifNotExists === self::IF_NOT_EXISTS_CREATE_NEW
+                ? $this->worksheet->createNewCell($cellAddress)
+                : null
+            );
     }
 
     /**

tests/PhpSpreadsheetTests/Worksheet/ColumnCellIterator2Test.php

@@ -3,6 +3,7 @@
 namespace PhpOffice\PhpSpreadsheetTests\Worksheet;
 
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PhpOffice\PhpSpreadsheet\Worksheet\CellIterator;
 use PhpOffice\PhpSpreadsheet\Worksheet\ColumnCellIterator;
 use PHPUnit\Framework\TestCase;
 
@@ -32,8 +33,8 @@ public function testEndRange(?bool $existing, string $expectedResultFirst, strin
                 }
             }
         }
-        self::assertEquals($expectedResultFirst, $firstCoordinate);
-        self::assertEquals($expectedResultLast, $lastCoordinate);
+        self::assertSame($expectedResultFirst, $firstCoordinate);
+        self::assertSame($expectedResultLast, $lastCoordinate);
     }
 
     public function providerExistingCell(): array
@@ -63,15 +64,63 @@ public function testEmptyColumn(?bool $existing, int $expectedResult): void
         foreach ($iterator as $cell) {
             ++$numCells;
         }
-        self::assertEquals($expectedResult, $numCells);
+        self::assertSame($expectedResult, $numCells);
     }
 
     public function providerEmptyColumn(): array
     {
         return [
-            [null, 6],
+            [null, 6], // Default behaviour
             [false, 6],
             [true, 0],
         ];
     }
+
+    /**
+     * @dataProvider providerNullOrCreate
+     */
+    public function testNullOrCreateOption(?bool $existingBehaviour, int $expectedCreatedResult): void
+    {
+        $spreadsheet = new Spreadsheet();
+        $sheet = $spreadsheet->getActiveSheet();
+        $iterator = new ColumnCellIterator($sheet, 'F');
+        if (isset($existingBehaviour)) {
+            $iterator->setIfNotExists($existingBehaviour);
+        }
+        $notExistsBehaviour = $iterator->getIfNotExists();
+        self::assertSame($expectedCreatedResult > 0, $notExistsBehaviour);
+    }
+
+    /**
+     * @dataProvider providerNullOrCreate
+     */
+    public function testNullOrCreate(?bool $existing, int $expectedCreatedResult, int $expectedNullResult): void
+    {
+        $spreadsheet = new Spreadsheet();
+        $sheet = $spreadsheet->getActiveSheet();
+        $sheet->getCell('B2')->setValue('cellb2');
+        $sheet->getCell('F4')->setValue('cellf2');
+
+        $iterator = new ColumnCellIterator($sheet, 'F');
+        if (isset($existing)) {
+            $iterator->setIfNotExists($existing);
+        }
+        $numCreatedCells = $numEmptyCells = 0;
+        foreach ($iterator as $cell) {
+            $numCreatedCells += (int) ($cell !== null && $cell->getValue() === null);
+            // @phpstan-ignore-next-line
+            $numEmptyCells += (int) ($cell === null);
+        }
+        self::assertSame($expectedCreatedResult, $numCreatedCells);
+        self::assertSame($expectedNullResult, $numEmptyCells);
+    }
+
+    public function providerNullOrCreate(): array
+    {
+        return [
+            [null, 3, 0], // Default behaviour
+            [CellIterator::IF_NOT_EXISTS_CREATE_NEW, 3, 0],
+            [CellIterator::IF_NOT_EXISTS_RETURN_NULL, 0, 3],
+        ];
+    }
 }

tests/PhpSpreadsheetTests/Worksheet/RowCellIterator2Test.php

@@ -3,6 +3,7 @@
 namespace PhpOffice\PhpSpreadsheetTests\Worksheet;
 
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PhpOffice\PhpSpreadsheet\Worksheet\CellIterator;
 use PhpOffice\PhpSpreadsheet\Worksheet\RowCellIterator;
 use PHPUnit\Framework\TestCase;
 
@@ -32,8 +33,8 @@ public function testEndRangeTrue(?bool $existing, string $expectedResultFirst, s
                 }
             }
         }
-        self::assertEquals($expectedResultFirst, $firstCoordinate);
-        self::assertEquals($expectedResultLast, $lastCoordinate);
+        self::assertSame($expectedResultFirst, $firstCoordinate);
+        self::assertSame($expectedResultLast, $lastCoordinate);
     }
 
     public function providerExistingCell(): array
@@ -63,15 +64,63 @@ public function testEmptyRow(?bool $existing, int $expectedResult): void
         foreach ($iterator as $cell) {
             ++$numCells;
         }
-        self::assertEquals($expectedResult, $numCells);
+        self::assertSame($expectedResult, $numCells);
     }
 
     public function providerEmptyRow(): array
     {
         return [
-            [null, 6],
+            [null, 6], // Default behaviour
             [false, 6],
             [true, 0],
         ];
     }
+
+    /**
+     * @dataProvider providerNullOrCreate
+     */
+    public function testNullOrCreateOption(?bool $existingBehaviour, int $expectedCreatedResult): void
+    {
+        $spreadsheet = new Spreadsheet();
+        $sheet = $spreadsheet->getActiveSheet();
+        $iterator = new RowCellIterator($sheet, 2);
+        if (isset($existingBehaviour)) {
+            $iterator->setIfNotExists($existingBehaviour);
+        }
+        $notExistsBehaviour = $iterator->getIfNotExists();
+        self::assertSame($expectedCreatedResult > 0, $notExistsBehaviour);
+    }
+
+    /**
+     * @dataProvider providerNullOrCreate
+     */
+    public function testNullOrCreate(?bool $existing, int $expectedCreatedResult, int $expectedNullResult): void
+    {
+        $spreadsheet = new Spreadsheet();
+        $sheet = $spreadsheet->getActiveSheet();
+        $sheet->getCell('B2')->setValue('cellb2');
+        $sheet->getCell('F2')->setValue('cellf2');
+
+        $iterator = new RowCellIterator($sheet, 2);
+        if (isset($existing)) {
+            $iterator->setIfNotExists($existing);
+        }
+        $numCreatedCells = $numEmptyCells = 0;
+        foreach ($iterator as $cell) {
+            $numCreatedCells += (int) ($cell !== null && $cell->getValue() === null);
+            // @phpstan-ignore-next-line
+            $numEmptyCells += (int) ($cell === null);
+        }
+        self::assertSame($expectedCreatedResult, $numCreatedCells);
+        self::assertSame($expectedNullResult, $numEmptyCells);
+    }
+
+    public function providerNullOrCreate(): array
+    {
+        return [
+            [null, 4, 0], // Default behaviour
+            [CellIterator::IF_NOT_EXISTS_CREATE_NEW, 4, 0],
+            [CellIterator::IF_NOT_EXISTS_RETURN_NULL, 0, 4],
+        ];
+    }
 }