From b783fecb7fd02c2f86854de1cbff7afac7bdf939 Mon Sep 17 00:00:00 2001
From: MarkBaker <mark@demon-angel.eu>
Date: Fri, 12 Aug 2022 14:03:13 +0200
Subject: [PATCH] More return type declarations, and some additional argument
 typehinting

---
 src/PhpSpreadsheet/Cell/Cell.php              | 92 +++++++------------
 src/PhpSpreadsheet/Collection/Cells.php       | 16 +---
 .../Collection/CellsFactory.php               |  3 +-
 src/PhpSpreadsheet/Worksheet/Worksheet.php    | 44 +++------
 4 files changed, 52 insertions(+), 103 deletions(-)

diff --git a/src/PhpSpreadsheet/Cell/Cell.php b/src/PhpSpreadsheet/Cell/Cell.php
index 2005694d..bc02fbf0 100644
--- a/src/PhpSpreadsheet/Cell/Cell.php
+++ b/src/PhpSpreadsheet/Cell/Cell.php
@@ -50,14 +50,14 @@ class Cell
     private $dataType;
 
     /**
-     * Collection of cells.
+     * The collection of cells that this cell belongs to (i.e. The Cell Collection for the parent Worksheet).
      *
      * @var Cells
      */
     private $parent;
 
     /**
-     * Index to cellXf.
+     * Index to the cellXf reference for the styling of this cell.
      *
      * @var int
      */
@@ -95,9 +95,8 @@ class Cell
      * Create a new Cell.
      *
      * @param mixed $value
-     * @param string $dataType
      */
-    public function __construct($value, $dataType, Worksheet $worksheet)
+    public function __construct($value, ?string $dataType, Worksheet $worksheet)
     {
         // Initialise cell value
         $this->value = $value;
@@ -111,7 +110,7 @@ class Cell
                 $dataType = DataType::TYPE_STRING;
             }
             $this->dataType = $dataType;
-        } elseif (!self::getValueBinder()->bindValue($this, $value)) {
+        } elseif (self::getValueBinder()->bindValue($this, $value) === false) {
             throw new Exception('Value could not be bound to cell.');
         }
     }
@@ -167,10 +166,8 @@ class Cell
 
     /**
      * Get cell value with formatting.
-     *
-     * @return string
      */
-    public function getFormattedValue()
+    public function getFormattedValue(): string
     {
         return (string) NumberFormat::toFormattedString(
             $this->getCalculatedValue(),
@@ -188,7 +185,7 @@ class Cell
      *
      * @return $this
      */
-    public function setValue($value)
+    public function setValue($value): self
     {
         if (!self::getValueBinder()->bindValue($this, $value)) {
             throw new Exception('Value could not be bound to cell.');
@@ -205,7 +202,7 @@ class Cell
      *        Note that PhpSpreadsheet does not validate that the value and datatype are consistent, in using this
      *             method, then it is your responsibility as an end-user developer to validate that the value and
      *             the datatype match.
-     *       If you do mismatch value and datatpe, then the value you enter may be changed to match the datatype
+     *       If you do mismatch value and datatype, then the value you enter may be changed to match the datatype
      *          that you specify.
      *
      * @return Cell
@@ -271,7 +268,7 @@ class Cell
      *
      * @return mixed
      */
-    public function getCalculatedValue($resetLog = true)
+    public function getCalculatedValue(bool $resetLog = true)
     {
         if ($this->dataType === DataType::TYPE_FORMULA) {
             try {
@@ -319,7 +316,7 @@ class Cell
      *
      * @return Cell
      */
-    public function setCalculatedValue($originalValue)
+    public function setCalculatedValue($originalValue): self
     {
         if ($originalValue !== null) {
             $this->calculatedValue = (is_numeric($originalValue)) ? (float) $originalValue : $originalValue;
@@ -345,10 +342,8 @@ class Cell
 
     /**
      * Get cell data type.
-     *
-     * @return string
      */
-    public function getDataType()
+    public function getDataType(): string
     {
         return $this->dataType;
     }
@@ -360,7 +355,7 @@ class Cell
      *
      * @return Cell
      */
-    public function setDataType($dataType)
+    public function setDataType($dataType): self
     {
         if ($dataType == DataType::TYPE_STRING2) {
             $dataType = DataType::TYPE_STRING;
@@ -392,10 +387,8 @@ class Cell
 
     /**
      * Get Data validation rules.
-     *
-     * @return DataValidation
      */
-    public function getDataValidation()
+    public function getDataValidation(): DataValidation
     {
         if (!isset($this->parent)) {
             throw new Exception('Cannot get data validation for cell that is not bound to a worksheet');
@@ -420,10 +413,8 @@ class Cell
 
     /**
      * Does this cell contain valid value?
-     *
-     * @return bool
      */
-    public function hasValidValue()
+    public function hasValidValue(): bool
     {
         $validator = new DataValidator();
 
@@ -432,10 +423,8 @@ class Cell
 
     /**
      * Does this cell contain a Hyperlink?
-     *
-     * @return bool
      */
-    public function hasHyperlink()
+    public function hasHyperlink(): bool
     {
         if (!isset($this->parent)) {
             throw new Exception('Cannot check for hyperlink when cell is not bound to a worksheet');
@@ -446,10 +435,8 @@ class Cell
 
     /**
      * Get Hyperlink.
-     *
-     * @return Hyperlink
      */
-    public function getHyperlink()
+    public function getHyperlink(): Hyperlink
     {
         if (!isset($this->parent)) {
             throw new Exception('Cannot get hyperlink for cell that is not bound to a worksheet');
@@ -463,7 +450,7 @@ class Cell
      *
      * @return Cell
      */
-    public function setHyperlink(?Hyperlink $hyperlink = null)
+    public function setHyperlink(?Hyperlink $hyperlink = null): self
     {
         if (!isset($this->parent)) {
             throw new Exception('Cannot set hyperlink for cell that is not bound to a worksheet');
@@ -486,10 +473,8 @@ class Cell
 
     /**
      * Get parent worksheet.
-     *
-     * @return Worksheet
      */
-    public function getWorksheet()
+    public function getWorksheet(): Worksheet
     {
         try {
             $worksheet = $this->parent->getParent();
@@ -506,27 +491,22 @@ class Cell
 
     /**
      * Is this cell in a merge range.
-     *
-     * @return bool
      */
-    public function isInMergeRange()
+    public function isInMergeRange(): bool
     {
         return (bool) $this->getMergeRange();
     }
 
     /**
      * Is this cell the master (top left cell) in a merge range (that holds the actual data value).
-     *
-     * @return bool
      */
-    public function isMergeRangeValueCell()
+    public function isMergeRangeValueCell(): bool
     {
         if ($mergeRange = $this->getMergeRange()) {
             $mergeRange = Coordinate::splitRange($mergeRange);
             [$startCell] = $mergeRange[0];
-            if ($this->getCoordinate() === $startCell) {
-                return true;
-            }
+
+            return $this->getCoordinate() === $startCell;
         }
 
         return false;
@@ -579,7 +559,7 @@ class Cell
      *
      * @return Cell
      */
-    public function rebindParent(Worksheet $parent)
+    public function rebindParent(Worksheet $parent): self
     {
         $this->parent = $parent->getCellCollection();
 
@@ -590,10 +570,8 @@ class Cell
      *    Is cell in a specific range?
      *
      * @param string $range Cell range (e.g. A1:A1)
-     *
-     * @return bool
      */
-    public function isInRange($range)
+    public function isInRange(string $range): bool
     {
         [$rangeStart, $rangeEnd] = Coordinate::rangeBoundaries($range);
 
@@ -614,7 +592,7 @@ class Cell
      *
      * @return int Result of comparison (always -1 or 1, never zero!)
      */
-    public static function compareCells(self $a, self $b)
+    public static function compareCells(self $a, self $b): int
     {
         if ($a->getRow() < $b->getRow()) {
             return -1;
@@ -629,10 +607,8 @@ class Cell
 
     /**
      * Get value binder to use.
-     *
-     * @return IValueBinder
      */
-    public static function getValueBinder()
+    public static function getValueBinder(): IValueBinder
     {
         if (self::$valueBinder === null) {
             self::$valueBinder = new DefaultValueBinder();
@@ -655,21 +631,19 @@ class Cell
     public function __clone()
     {
         $vars = get_object_vars($this);
-        foreach ($vars as $key => $value) {
-            if ((is_object($value)) && ($key != 'parent')) {
-                $this->$key = clone $value;
+        foreach ($vars as $propertyName => $propertyValue) {
+            if ((is_object($propertyValue)) && ($propertyName !== 'parent')) {
+                $this->$propertyName = clone $propertyValue;
             } else {
-                $this->$key = $value;
+                $this->$propertyName = $propertyValue;
             }
         }
     }
 
     /**
      * Get index to cellXf.
-     *
-     * @return int
      */
-    public function getXfIndex()
+    public function getXfIndex(): int
     {
         return $this->xfIndex;
     }
@@ -677,11 +651,9 @@ class Cell
     /**
      * Set index to cellXf.
      *
-     * @param int $indexValue
-     *
      * @return Cell
      */
-    public function setXfIndex($indexValue)
+    public function setXfIndex(int $indexValue): self
     {
         $this->xfIndex = $indexValue;
 
@@ -695,7 +667,7 @@ class Cell
      *
      * @return $this
      */
-    public function setFormulaAttributes($attributes)
+    public function setFormulaAttributes($attributes): self
     {
         $this->formulaAttributes = $attributes;
 
diff --git a/src/PhpSpreadsheet/Collection/Cells.php b/src/PhpSpreadsheet/Collection/Cells.php
index 20fccf48..03ad1cd4 100644
--- a/src/PhpSpreadsheet/Collection/Cells.php
+++ b/src/PhpSpreadsheet/Collection/Cells.php
@@ -91,10 +91,8 @@ class Cells
      * Whether the collection holds a cell for the given coordinate.
      *
      * @param string $cellCoordinate Coordinate of the cell to check
-     *
-     * @return bool
      */
-    public function has($cellCoordinate)
+    public function has($cellCoordinate): bool
     {
         return ($cellCoordinate === $this->currentCoordinate) || isset($this->index[$cellCoordinate]);
     }
@@ -103,10 +101,8 @@ class Cells
      * Add or update a cell in the collection.
      *
      * @param Cell $cell Cell to update
-     *
-     * @return Cell
      */
-    public function update(Cell $cell)
+    public function update(Cell $cell): Cell
     {
         return $this->add($cell->getCoordinate(), $cell);
     }
@@ -165,10 +161,8 @@ class Cells
 
     /**
      * Return the column coordinate of the currently active cell object.
-     *
-     * @return string
      */
-    public function getCurrentColumn()
+    public function getCurrentColumn(): string
     {
         sscanf($this->currentCoordinate ?? '', '%[A-Z]%d', $column, $row);
 
@@ -177,10 +171,8 @@ class Cells
 
     /**
      * Return the row coordinate of the currently active cell object.
-     *
-     * @return int
      */
-    public function getCurrentRow()
+    public function getCurrentRow(): int
     {
         sscanf($this->currentCoordinate ?? '', '%[A-Z]%d', $column, $row);
 
diff --git a/src/PhpSpreadsheet/Collection/CellsFactory.php b/src/PhpSpreadsheet/Collection/CellsFactory.php
index 26f18dfc..b3833bd8 100644
--- a/src/PhpSpreadsheet/Collection/CellsFactory.php
+++ b/src/PhpSpreadsheet/Collection/CellsFactory.php
@@ -12,9 +12,8 @@ abstract class CellsFactory
      *
      * @param Worksheet $worksheet Enable cell caching for this worksheet
      *
-     * @return Cells
      * */
-    public static function getInstance(Worksheet $worksheet)
+    public static function getInstance(Worksheet $worksheet): Cells
     {
         return new Cells($worksheet, Settings::getCache());
     }
diff --git a/src/PhpSpreadsheet/Worksheet/Worksheet.php b/src/PhpSpreadsheet/Worksheet/Worksheet.php
index e89043c8..13cd4f61 100644
--- a/src/PhpSpreadsheet/Worksheet/Worksheet.php
+++ b/src/PhpSpreadsheet/Worksheet/Worksheet.php
@@ -1336,7 +1336,7 @@ class Worksheet implements IComparable
      *
      * @return Cell Cell that was created
      */
-    public function createNewCell($coordinate)
+    public function createNewCell($coordinate): Cell
     {
         [$column, $row, $columnString] = Coordinate::indexesFromString($coordinate);
         $cell = new Cell(null, DataType::TYPE_NULL, $this);
@@ -2459,10 +2459,8 @@ class Worksheet implements IComparable
 
     /**
      * Show gridlines?
-     *
-     * @return bool
      */
-    public function getShowGridlines()
+    public function getShowGridlines(): bool
     {
         return $this->showGridlines;
     }
@@ -2474,7 +2472,7 @@ class Worksheet implements IComparable
      *
      * @return $this
      */
-    public function setShowGridlines($showGridLines)
+    public function setShowGridlines(bool $showGridLines): self
     {
         $this->showGridlines = $showGridLines;
 
@@ -2483,10 +2481,8 @@ class Worksheet implements IComparable
 
     /**
      * Print gridlines?
-     *
-     * @return bool
      */
-    public function getPrintGridlines()
+    public function getPrintGridlines(): bool
     {
         return $this->printGridlines;
     }
@@ -2498,7 +2494,7 @@ class Worksheet implements IComparable
      *
      * @return $this
      */
-    public function setPrintGridlines($printGridLines)
+    public function setPrintGridlines(bool $printGridLines): self
     {
         $this->printGridlines = $printGridLines;
 
@@ -2507,10 +2503,8 @@ class Worksheet implements IComparable
 
     /**
      * Show row and column headers?
-     *
-     * @return bool
      */
-    public function getShowRowColHeaders()
+    public function getShowRowColHeaders(): bool
     {
         return $this->showRowColHeaders;
     }
@@ -2522,7 +2516,7 @@ class Worksheet implements IComparable
      *
      * @return $this
      */
-    public function setShowRowColHeaders($showRowColHeaders)
+    public function setShowRowColHeaders(bool $showRowColHeaders): self
     {
         $this->showRowColHeaders = $showRowColHeaders;
 
@@ -2531,10 +2525,8 @@ class Worksheet implements IComparable
 
     /**
      * Show summary below? (Row/Column outlining).
-     *
-     * @return bool
      */
-    public function getShowSummaryBelow()
+    public function getShowSummaryBelow(): bool
     {
         return $this->showSummaryBelow;
     }
@@ -2546,7 +2538,7 @@ class Worksheet implements IComparable
      *
      * @return $this
      */
-    public function setShowSummaryBelow($showSummaryBelow)
+    public function setShowSummaryBelow(bool $showSummaryBelow): self
     {
         $this->showSummaryBelow = $showSummaryBelow;
 
@@ -2555,10 +2547,8 @@ class Worksheet implements IComparable
 
     /**
      * Show summary right? (Row/Column outlining).
-     *
-     * @return bool
      */
-    public function getShowSummaryRight()
+    public function getShowSummaryRight(): bool
     {
         return $this->showSummaryRight;
     }
@@ -2570,7 +2560,7 @@ class Worksheet implements IComparable
      *
      * @return $this
      */
-    public function setShowSummaryRight($showSummaryRight)
+    public function setShowSummaryRight(bool $showSummaryRight): self
     {
         $this->showSummaryRight = $showSummaryRight;
 
@@ -2594,7 +2584,7 @@ class Worksheet implements IComparable
      *
      * @return $this
      */
-    public function setComments(array $comments)
+    public function setComments(array $comments): self
     {
         $this->comments = $comments;
 
@@ -2609,7 +2599,7 @@ class Worksheet implements IComparable
      *
      * @return $this
      */
-    public function removeComment($cellCoordinate)
+    public function removeComment($cellCoordinate): self
     {
         $cellAddress = Functions::trimSheetFromCellReference(Validations::validateCellAddress($cellCoordinate));
 
@@ -2633,10 +2623,8 @@ class Worksheet implements IComparable
      *
      * @param array<int>|CellAddress|string $cellCoordinate Coordinate of the cell as a string, eg: 'C5';
      *               or as an array of [$columnIndex, $row] (e.g. [3, 5]), or a CellAddress object.
-     *
-     * @return Comment
      */
-    public function getComment($cellCoordinate)
+    public function getComment($cellCoordinate): Comment
     {
         $cellAddress = Functions::trimSheetFromCellReference(Validations::validateCellAddress($cellCoordinate));
 
@@ -2669,10 +2657,8 @@ class Worksheet implements IComparable
      *
      * @param int $columnIndex Numeric column coordinate of the cell
      * @param int $row Numeric row coordinate of the cell
-     *
-     * @return Comment
      */
-    public function getCommentByColumnAndRow($columnIndex, $row)
+    public function getCommentByColumnAndRow($columnIndex, $row): Comment
     {
         return $this->getComment(Coordinate::stringFromColumnIndex($columnIndex) . $row);
     }