Add functionality to adjust CellRange by "modifying" the from/to CellAddress Value objects

Author: MarkBaker

.php-cs-fixer.dist.php

@@ -21,7 +21,7 @@
         'braces' => true,
         'cast_spaces' => true,
         'class_attributes_separation' => ['elements' => ['method' => 'one', 'property' => 'one']], // const are often grouped with other related const
-        'class_definition' => true,
+        'class_definition' => false,
         'class_keyword_remove' => false, // ::class keyword gives us better support in IDE
         'combine_consecutive_issets' => true,
         'combine_consecutive_unsets' => true,

CHANGELOG.md

@@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
-- Implementation of the FILTER(), SORT(), SORTBY() and UNIQUE() Lookup/Reference (array) functions
+- Introduced CellAddress, CellRange, RowRange and ColumnRange value objects that can be used as an alternative to a string value (e.g. `'C5'`, `'B2:D4'`, `'2:2'` or `'B:C'`) in appropriate contexts.
+- Implementation of the FILTER(), SORT(), SORTBY() and UNIQUE() Lookup/Reference (array) functions.
 - Implementation of the ISREF() Information function.
 - Added support for reading "formatted" numeric values from Csv files; although default behaviour of reading these values as strings is preserved.
 

src/PhpSpreadsheet/Cell/CellAddress.php

@@ -32,7 +32,7 @@ class CellAddress
      */
     protected $rowId;
 
-    protected function __construct(string $cellAddress, ?Worksheet $worksheet)
+    public function __construct(string $cellAddress, ?Worksheet $worksheet)
     {
         $this->cellAddress = str_replace('$', '', $cellAddress);
         [$this->columnName, $rowId] = Coordinate::coordinateFromString($cellAddress);

src/PhpSpreadsheet/Cell/CellRange.php

@@ -34,8 +34,8 @@ private function validateFromTo(CellAddress $from, CellAddress $to): void
         $toWorksheet = $to->worksheet();
         $this->validateWorksheets($fromWorksheet, $toWorksheet);
 
-        $this->from = CellAddress::fromColumnAndRow($firstColumn, $firstRow, $fromWorksheet);
-        $this->to = CellAddress::fromColumnAndRow($lastColumn, $lastRow, $toWorksheet);
+        $this->from = $this->cellAddressWrapper($firstColumn, $firstRow, $fromWorksheet);
+        $this->to = $this->cellAddressWrapper($lastColumn, $lastRow, $toWorksheet);
     }
 
     private function validateWorksheets(?Worksheet $fromWorksheet, ?Worksheet $toWorksheet): void
@@ -54,18 +54,76 @@ private function validateWorksheets(?Worksheet $fromWorksheet, ?Worksheet $toWor
         }
     }
 
+    private function cellAddressWrapper(int $column, int $row, ?Worksheet $worksheet = null): CellAddress
+    {
+        $cellAddress = Coordinate::stringFromColumnIndex($column) . (string) $row;
+
+        return new class ($cellAddress, $worksheet) extends CellAddress {
+            public function nextRow(int $offset = 1): CellAddress
+            {
+                /** @var CellAddress $result */
+                $result = parent::nextRow($offset);
+                $this->rowId = $result->rowId;
+                $this->cellAddress = $result->cellAddress;
+
+                return $this;
+            }
+
+            public function previousRow(int $offset = 1): CellAddress
+            {
+                /** @var CellAddress $result */
+                $result = parent::previousRow($offset);
+                $this->rowId = $result->rowId;
+                $this->cellAddress = $result->cellAddress;
+
+                return $this;
+            }
+
+            public function nextColumn(int $offset = 1): CellAddress
+            {
+                /** @var CellAddress $result */
+                $result = parent::nextColumn($offset);
+                $this->columnId = $result->columnId;
+                $this->columnName = $result->columnName;
+                $this->cellAddress = $result->cellAddress;
+
+                return $this;
+            }
+
+            public function previousColumn(int $offset = 1): CellAddress
+            {
+                /** @var CellAddress $result */
+                $result = parent::previousColumn($offset);
+                $this->columnId = $result->columnId;
+                $this->columnName = $result->columnName;
+                $this->cellAddress = $result->cellAddress;
+
+                return $this;
+            }
+        };
+    }
+
     public function from(): CellAddress
     {
+        // Re-order from/to in case the cell addresses have been modified
+        $this->validateFromTo($this->from, $this->to);
+
         return $this->from;
     }
 
     public function to(): CellAddress
     {
+        // Re-order from/to in case the cell addresses have been modified
+        $this->validateFromTo($this->from, $this->to);
+
         return $this->to;
     }
 
     public function __toString(): string
     {
+        // Re-order from/to in case the cell addresses have been modified
+        $this->validateFromTo($this->from, $this->to);
+
         if ($this->from->cellAddress() === $this->to->cellAddress()) {
             return "{$this->from->fullCellAddress()}";
         }

tests/PhpSpreadsheetTests/Cell/CellRangeTest.php

@@ -110,4 +110,34 @@ public function testCreateCellRangeWithMismatchedSpreadsheets(): void
         $to = CellAddress::fromCellAddress('E2', $worksheet2);
         new CellRange($from, $to);
     }
+
+    public function testShiftRangeTo(): void
+    {
+        $from = CellAddress::fromCellAddress('B5');
+        $to = CellAddress::fromCellAddress('E2');
+        $cellRange = new CellRange($from, $to);
+        self::assertSame('B2:E5', (string) $cellRange);
+
+        $cellRange->to()->nextColumn(2);
+        $cellRange->to()->nextRow(2);
+
+        self::assertSame('B2', (string) $cellRange->from());
+        self::assertSame('G7', (string) $cellRange->to());
+        self::assertSame('B2:G7', (string) $cellRange);
+    }
+
+    public function testShiftRangeFrom(): void
+    {
+        $from = CellAddress::fromCellAddress('B5');
+        $to = CellAddress::fromCellAddress('E2');
+        $cellRange = new CellRange($from, $to);
+        self::assertSame('B2:E5', (string) $cellRange);
+
+        $cellRange->from()->nextColumn(5);
+        $cellRange->from()->nextRow(5);
+
+        self::assertSame('E5', (string) $cellRange->from());
+        self::assertSame('G7', (string) $cellRange->to());
+        self::assertSame('E5:G7', (string) $cellRange);
+    }
 }