Merge pull request #4452 from oleibman/stan1003write

More Phpstan Level 10 Prep - Writers

Author: oleibman

phpstan.neon.dist

@@ -28,4 +28,5 @@ parameters:
         # Accept a bit anything for assert methods
         - '~^Parameter \#2 .* of static method PHPUnit\\Framework\\Assert\:\:assert\w+\(\) expects .*, .* given\.$~'
         #- '~Method .*rovider.* return type has no value type specified in iterable type array\.$~'
+        #- '~Method .*rovider.* should return array but returns mixed\.$~'
         - identifier: missingType.iterableValue

src/PhpSpreadsheet/Cell/Coordinate.php

@@ -3,6 +3,7 @@
 namespace PhpOffice\PhpSpreadsheet\Cell;
 
 use PhpOffice\PhpSpreadsheet\Exception;
+use PhpOffice\PhpSpreadsheet\Shared\StringHelper;
 use PhpOffice\PhpSpreadsheet\Worksheet\Validations;
 use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;
 
@@ -162,7 +163,7 @@ public static function splitRange(string $range): array
     /**
      * Build range from coordinate strings.
      *
-     * @param array $range Array containing one or more arrays containing one or two coordinate strings
+     * @param mixed[] $range Array containing one or more arrays containing one or two coordinate strings
      *
      * @return string String representation of $pRange
      */
@@ -187,7 +188,7 @@ public static function buildRange(array $range): string
      *
      * @param string $range Cell range, Single Cell, Row/Column Range (e.g. A1:A1, B2, B:C, 2:3)
      *
-     * @return array Range coordinates [Start Cell, End Cell]
+     * @return array{array{int, int}, array{int, int}} Range coordinates [Start Cell, End Cell]
      *                    where Start Cell and End Cell are arrays (Column Number, Row Number)
      */
     public static function rangeBoundaries(string $range): array
@@ -224,6 +225,8 @@ public static function rangeBoundaries(string $range): array
         // Translate column into index
         $rangeStart[0] = self::columnIndexFromString($rangeStart[0]);
         $rangeEnd[0] = self::columnIndexFromString($rangeEnd[0]);
+        $rangeStart[1] = (int) $rangeStart[1];
+        $rangeEnd[1] = (int) $rangeEnd[1];
 
         return [$rangeStart, $rangeEnd];
     }
@@ -233,7 +236,7 @@ public static function rangeBoundaries(string $range): array
      *
      * @param string $range Cell range, Single Cell, Row/Column Range (e.g. A1:A1, B2, B:C, 2:3)
      *
-     * @return array Range dimension (width, height)
+     * @return array{int, int} Range dimension (width, height)
      */
     public static function rangeDimension(string $range): array
     {
@@ -248,7 +251,7 @@ public static function rangeDimension(string $range): array
      *
      * @param string $range Cell range, Single Cell, Row/Column Range (e.g. A1:A1, B2, B:C, 2:3)
      *
-     * @return array Range coordinates [Start Cell, End Cell]
+     * @return array{array{string, int}, array{string, int}} Range coordinates [Start Cell, End Cell]
      *                    where Start Cell and End Cell are arrays [Column ID, Row Number]
      */
     public static function getRangeBoundaries(string $range): array
@@ -267,7 +270,7 @@ public static function getRangeBoundaries(string $range): array
      *
      * @param string $reference Coordinate or Range (e.g. A1:A1, B2, B:C, 2:3)
      *
-     * @return array reference data
+     * @return array{type: string, firstCoordinate?: string, secondCoordinate?: string, coordinate?: string, worksheet?: string, localReference?: string} reference data
      */
     private static function validateReferenceAndGetData($reference): array
     {
@@ -331,7 +334,13 @@ public static function coordinateIsInsideRange(string $range, string $coordinate
             }
         }
 
+        if (!isset($rangeData['localReference'])) {
+            return false;
+        }
         $boundaries = self::rangeBoundaries($rangeData['localReference']);
+        if (!isset($coordinateData['localReference'])) {
+            return false;
+        }
         $coordinates = self::indexesFromString($coordinateData['localReference']);
 
         $columnIsInside = $boundaries[0][0] <= $coordinates[0] && $coordinates[0] <= $boundaries[1][0];
@@ -358,6 +367,7 @@ public static function columnIndexFromString(?string $columnAddress): int
         //    Using a lookup cache adds a slight memory overhead, but boosts speed
         //    caching using a static within the method is faster than a class static,
         //        though it's additional memory overhead
+        /** @var int[] */
         static $indexCache = [];
         $columnAddress = $columnAddress ?? '';
 
@@ -367,6 +377,7 @@ public static function columnIndexFromString(?string $columnAddress): int
         //    It's surprising how costly the strtoupper() and ord() calls actually are, so we use a lookup array
         //        rather than use ord() and make it case insensitive to get rid of the strtoupper() as well.
         //        Because it's a static, there's no significant memory overhead either.
+        /** @var array<string, int> */
         static $columnLookup = [
             'A' => 1, 'B' => 2, 'C' => 3, 'D' => 4, 'E' => 5, 'F' => 6, 'G' => 7, 'H' => 8, 'I' => 9, 'J' => 10,
             'K' => 11, 'L' => 12, 'M' => 13, 'N' => 14, 'O' => 15, 'P' => 16, 'Q' => 17, 'R' => 18, 'S' => 19,
@@ -402,23 +413,25 @@ public static function columnIndexFromString(?string $columnAddress): int
         );
     }
 
+    private const LOOKUP_CACHE = ' ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
     /**
      * String from column index.
      *
      * @param int|numeric-string $columnIndex Column index (A = 1)
      */
     public static function stringFromColumnIndex(int|string $columnIndex): string
     {
+        /** @var string[] */
         static $indexCache = [];
-        static $lookupCache = ' ABCDEFGHIJKLMNOPQRSTUVWXYZ';
 
         if (!isset($indexCache[$columnIndex])) {
             $indexValue = $columnIndex;
             $base26 = '';
             do {
                 $characterValue = ($indexValue % 26) ?: 26;
                 $indexValue = ($indexValue - $characterValue) / 26;
-                $base26 = $lookupCache[$characterValue] . $base26;
+                $base26 = self::LOOKUP_CACHE[$characterValue] . $base26;
             } while ($indexValue > 0);
             $indexCache[$columnIndex] = $base26;
         }
@@ -431,7 +444,7 @@ public static function stringFromColumnIndex(int|string $columnIndex): string
      *
      * @param string $cellRange Range: e.g. 'A1' or 'A1:C10' or 'A1:E10,A20:E25' or 'A1:E5 C3:G7' or 'A1:C1,A3:C3 B1:C3'
      *
-     * @return array Array containing single cell references
+     * @return string[] Array containing single cell references
      */
     public static function extractAllCellReferencesInRange(string $cellRange): array
     {
@@ -452,23 +465,35 @@ public static function extractAllCellReferencesInRange(string $cellRange): array
 
         $cells = [];
         foreach ($ranges as $range) {
+            /** @var string $range */
             $cells[] = self::getReferencesForCellBlock($range);
         }
 
+        /** @var mixed[] */
         $cells = self::processRangeSetOperators($operators, $cells);
 
         if (empty($cells)) {
             return [];
         }
 
-        $cellList = array_merge(...$cells);
+        /** @var string[] */
+        $cellList = array_merge(...$cells); //* @phpstan-ignore-line
+        // Unsure how to satisfy phpstan in line above
 
-        return array_map(
-            fn ($cellAddress) => ($worksheet !== '') ? "{$quoted}{$worksheet}{$quoted}!{$cellAddress}" : $cellAddress,
+        $retVal = array_map(
+            fn (string $cellAddress) => ($worksheet !== '') ? "{$quoted}{$worksheet}{$quoted}!{$cellAddress}" : $cellAddress,
             self::sortCellReferenceArray($cellList)
         );
+
+        return $retVal;
     }
 
+    /**
+     * @param mixed[] $operators
+     * @param mixed[][] $cells
+     *
+     * @return mixed[]
+     */
     private static function processRangeSetOperators(array $operators, array $cells): array
     {
         $operatorCount = count($operators);
@@ -489,6 +514,11 @@ private static function processRangeSetOperators(array $operators, array $cells)
         return $cells;
     }
 
+    /**
+     * @param string[] $cellList
+     *
+     * @return string[]
+     */
     private static function sortCellReferenceArray(array $cellList): array
     {
         //    Sort the result by column and row
@@ -497,6 +527,7 @@ private static function sortCellReferenceArray(array $cellList): array
             $column = '';
             $row = 0;
             sscanf($coordinate, '%[A-Z]%d', $column, $row);
+            /** @var int $row */
             $key = (--$row * 16384) + self::columnIndexFromString((string) $column);
             $sortKeys[$key] = $coordinate;
         }
@@ -548,7 +579,7 @@ public static function resolveUnionAndIntersection(string $cellBlock, string $im
      *
      * @param string $cellBlock A cell range e.g. A4:B5
      *
-     * @return array All individual cells in that range
+     * @return string[] All individual cells in that range
      */
     private static function getReferencesForCellBlock(string $cellBlock): array
     {
@@ -585,6 +616,8 @@ private static function getReferencesForCellBlock(string $cellBlock): array
 
             // Loop cells
             while ($currentColumnIndex < $endColumnIndex) {
+                /** @var int $currentRow */
+                /** @var int $endRow */
                 while ($currentRow <= $endRow) {
                     $returnValue[] = self::stringFromColumnIndex($currentColumnIndex) . $currentRow;
                     ++$currentRow;
@@ -610,9 +643,9 @@ private static function getReferencesForCellBlock(string $cellBlock): array
      *
      *    [ 'A1:A3' => 'x', 'A4' => 'y' ]
      *
-     * @param array $coordinateCollection associative array mapping coordinates to values
+     * @param array<string, mixed> $coordinateCollection associative array mapping coordinates to values
      *
-     * @return array associative array mapping coordinate ranges to valuea
+     * @return array<string, mixed> associative array mapping coordinate ranges to valuea
      */
     public static function mergeRangesInCollection(array $coordinateCollection): array
     {
@@ -628,7 +661,7 @@ public static function mergeRangesInCollection(array $coordinateCollection): arr
 
             [$column, $row] = self::coordinateFromString($coord);
             $row = (int) (ltrim($row, '$'));
-            $hashCode = $column . '-' . ((is_object($value) && method_exists($value, 'getHashCode')) ? $value->getHashCode() : $value);
+            $hashCode = $column . '-' . StringHelper::convertToString((is_object($value) && method_exists($value, 'getHashCode')) ? $value->getHashCode() : $value);
 
             if (!isset($hashedValues[$hashCode])) {
                 $hashedValues[$hashCode] = (object) [
@@ -687,7 +720,7 @@ public static function mergeRangesInCollection(array $coordinateCollection): arr
      * Get the individual cell blocks from a range string, removing any $ characters.
      *      then splitting by operators and returning an array with ranges and operators.
      *
-     * @return array[]
+     * @return mixed[][]
      */
     private static function getCellBlocksFromRangeString(string $rangeString): array
     {

src/PhpSpreadsheet/Chart/Chart.php

@@ -490,7 +490,7 @@ public function setBottomRightPosition(string $cellAddress = '', ?int $xOffset =
     /**
      * Get the bottom right position of the chart.
      *
-     * @return array an associative array containing the cell address, X-Offset and Y-Offset from the top left of that cell
+     * @return array{cell: string, xOffset: int, yOffset:int} an associative array containing the cell address, X-Offset and Y-Offset from the top left of that cell
      */
     public function getBottomRightPosition(): array
     {

src/PhpSpreadsheet/Chart/PlotArea.php

@@ -17,7 +17,7 @@ class PlotArea
      *     First is position in %.
      *     Second is ChartColor.
      *
-     * @var array[]
+     * @var array<array{float, ChartColor}>
      */
     private array $gradientFillStops = [];
 
@@ -126,6 +126,7 @@ public function getNoFill(): bool
         return $this->noFill;
     }
 
+    /** @param array<array{float, ChartColor}> $gradientFillStops */
     public function setGradientFillProperties(array $gradientFillStops, ?float $gradientFillAngle): self
     {
         $this->gradientFillStops = $gradientFillStops;
@@ -144,6 +145,8 @@ public function getGradientFillAngle(): ?float
 
     /**
      * Get gradientFillStops.
+     *
+     * @return array<array{float, ChartColor}>
      */
     public function getGradientFillStops(): array
     {

src/PhpSpreadsheet/Chart/Title.php

@@ -46,6 +46,8 @@ public function __construct(array|RichText|string $caption = '', ?Layout $layout
 
     /**
      * Get caption.
+     *
+     * @return array<RichText|string>|RichText|string
      */
     public function getCaption(): array|RichText|string
     {

src/PhpSpreadsheet/Reader/BaseReader.php

@@ -112,11 +112,13 @@ public function setIncludeCharts(bool $includeCharts): self
         return $this;
     }
 
+    /** @return null|string[] */
     public function getLoadSheetsOnly(): ?array
     {
         return $this->loadSheetsOnly;
     }
 
+    /** @param null|string|string[] $sheetList */
     public function setLoadSheetsOnly(string|array|null $sheetList): self
     {
         if ($sheetList === null) {

src/PhpSpreadsheet/Reader/Csv.php

@@ -228,6 +228,7 @@ public function listWorksheetInfo(string $filename): array
         $this->checkSeparator();
         $this->inferSeparator();
 
+        /** @var array<int, array{worksheetName: string, lastColumnLetter: string, lastColumnIndex: int, totalRows: int, totalColumns: int, sheetState: string}> */
         $worksheetInfo = [];
         $worksheetInfo[0]['worksheetName'] = 'Worksheet';
         $worksheetInfo[0]['lastColumnLetter'] = 'A';

src/PhpSpreadsheet/Reader/Csv/Delimiter.php

@@ -13,6 +13,7 @@ class Delimiter
 
     protected string $enclosure;
 
+    /** @var array<string, int[]> */
     protected array $counts = [];
 
     protected int $numberLines = 0;
@@ -53,6 +54,7 @@ protected function countPotentialDelimiters(): void
         }
     }
 
+    /** @param array<string, int> $delimiterKeys */
     protected function countDelimiterValues(string $line, array $delimiterKeys): void
     {
         $splitString = mb_str_split($line, 1, 'UTF-8');
@@ -69,7 +71,7 @@ public function infer(): ?string
         // Calculate the mean square deviations for each delimiter
         //     (ignoring delimiters that haven't been found consistently)
         $meanSquareDeviations = [];
-        $middleIdx = floor(($this->numberLines - 1) / 2);
+        $middleIdx = (int) floor(($this->numberLines - 1) / 2);
 
         foreach (self::POTENTIAL_DELIMETERS as $delimiter) {
             $series = $this->counts[$delimiter];

src/PhpSpreadsheet/Reader/Gnumeric.php

@@ -38,6 +38,8 @@ class Gnumeric extends BaseReader
 
     /**
      * Shared Expressions.
+     *
+     * @var array<array{column: int, row: int, formula:string}>
      */
     private array $expressions = [];
 
@@ -48,6 +50,7 @@ class Gnumeric extends BaseReader
 
     private ReferenceHelper $referenceHelper;
 
+    /** @var array{'dataType': string[]} */
     public static array $mappings = [
         'dataType' => [
             '10' => DataType::TYPE_NULL,
@@ -96,6 +99,8 @@ private static function matchXml(XMLReader $xml, string $expectedLocalName): boo
 
     /**
      * Reads names of the worksheets from a file, without parsing the whole file to a Spreadsheet object.
+     *
+     * @return string[]
      */
     public function listWorksheetNames(string $filename): array
     {
@@ -203,6 +208,7 @@ private function gzfileGetContents(string $filename): string
         return $data;
     }
 
+    /** @return mixed[] */
     public static function gnumericMappings(): array
     {
         return array_merge(self::$mappings, Styles::$mappings);
@@ -559,8 +565,8 @@ private function loadCell(
             if (((string) $cell) > '') {
                 // Formula
                 $this->expressions[$ExprID] = [
-                    'column' => $cellAttributes->Col,
-                    'row' => $cellAttributes->Row,
+                    'column' => (int) $cellAttributes->Col,
+                    'row' => (int) $cellAttributes->Row,
                     'formula' => (string) $cell,
                 ];
             } else {

src/PhpSpreadsheet/Reader/Gnumeric/PageSetup.php

@@ -70,6 +70,11 @@ public function sheetMargins(SimpleXMLElement $sheet): self
         return $this;
     }
 
+    /**
+     * @param float[] $marginSet
+     *
+     * @return float[]
+     */
     private function buildMarginSet(SimpleXMLElement $sheet, array $marginSet): array
     {
         foreach ($sheet->PrintInformation->Margins->children(Gnumeric::NAMESPACE_GNM) as $key => $margin) {
@@ -83,6 +88,7 @@ private function buildMarginSet(SimpleXMLElement $sheet, array $marginSet): arra
         return $marginSet;
     }
 
+    /** @param float[] $marginSet */
     private function adjustMargins(array $marginSet): void
     {
         foreach ($marginSet as $key => $marginSize) {