Better Definitions for Mixed Parameters and Values Part 4 of Many

Continuing work started with PR PHPOffice#4016, PR PHPOffice#4026, and PR PHPOffice#4060. Improve documentation within program by making explicit what types of values are allowed for variables described as "mixed". In order to avoid broken functionality, this is done mainly through doc-blocks. This will get us closer to Phpstan Level 9, but many changes will be needed before we can consider that.

After this PR, 231 changes remain, all in src/Calculation.

Author: Owen Leibman

src/PhpSpreadsheet/Cell/Cell.php

@@ -191,7 +191,7 @@ public function getFormattedValue(): string
         $currentCalendar = SharedDate::getExcelCalendar();
         SharedDate::setExcelCalendar($this->getWorksheet()->getParent()?->getExcelCalendar());
         $formattedValue = (string) NumberFormat::toFormattedString(
-            $this->getCalculatedValue(),
+            $this->getCalculatedValueString(),
             (string) $this->getStyle()->getNumberFormat()->getFormatCode(true)
         );
         SharedDate::setExcelCalendar($currentCalendar);
@@ -920,7 +920,7 @@ public function setXfIndex(int $indexValue): self
      *
      * @return $this
      */
-    public function setFormulaAttributes(mixed $attributes): self
+    public function setFormulaAttributes(?array $attributes): self
     {
         $this->formulaAttributes = $attributes;
 

src/PhpSpreadsheet/Reader/Xlsx.php

@@ -60,8 +60,8 @@ public function testTooMuchPrecision(mixed $expectedResult, float|int|string $va
         $sheet = $this->getSheet();
         $sheet->getCell('E1')->setValue($value);
         $sheet->getCell('E2')->setValue("=TRUNC(E1,$digits)");
-        $result = $sheet->getCell('E2')->getCalculatedValue();
-        self::assertSame($expectedResult, (string) $result);
+        $result = $sheet->getCell('E2')->getCalculatedValueString();
+        self::assertSame($expectedResult, $result);
     }
 
     public static function providerTooMuchPrecision(): array

tests/PhpSpreadsheetTests/Calculation/Functions/MathTrig/TruncTest.php

@@ -30,6 +30,7 @@ public function testCONCATENATE(mixed $expectedResult, mixed ...$args): void
                 $finalArg .= 'A3';
                 $sheet->getCell('A3')->setValue(str_repeat('Ԁ', DataType::MAX_STRING_LENGTH - 5));
             } else {
+                self::assertTrue($arg === null || is_scalar($arg));
                 $finalArg .= '"' . (string) $arg . '"';
             }
         }

tests/PhpSpreadsheetTests/Calculation/Functions/TextData/ConcatenateTest.php

@@ -26,7 +26,7 @@ public function testArrayFormulaReader(
         $cell = $worksheet->getCell($cellAddress);
         self::assertSame(DataType::TYPE_FORMULA, $cell->getDataType());
         self::assertSame(['t' => 'array', 'ref' => $expectedRange], $cell->getFormulaAttributes());
-        self::assertSame($expectedFormula, strtoupper($cell->getValue()));
+        self::assertSame($expectedFormula, strtoupper($cell->getValueString()));
         Calculation::getInstance($spreadsheet)->setInstanceArrayReturnType(Calculation::RETURN_ARRAY_AS_ARRAY);
         $worksheet->calculateArrays();
         $cell = $worksheet->getCell($cellAddress);

tests/PhpSpreadsheetTests/Reader/Gnumeric/ArrayFormula2Test.php

@@ -30,7 +30,7 @@ public function testArrayFormulaReader(
         } else {
             self::assertEmpty($cell->getFormulaAttributes());
         }
-        self::assertSame($expectedFormula, strtoupper($cell->getValue()));
+        self::assertSame($expectedFormula, strtoupper($cell->getValueString()));
         Calculation::getInstance($spreadsheet)->setInstanceArrayReturnType(Calculation::RETURN_ARRAY_AS_ARRAY);
         $worksheet->calculateArrays();
         $cell = $worksheet->getCell($cellAddress);

tests/PhpSpreadsheetTests/Reader/Gnumeric/ArrayFormulaTest.php

@@ -26,7 +26,7 @@ public function testArrayFormulaReader(
         $cell = $worksheet->getCell($cellAddress);
         self::assertSame(DataType::TYPE_FORMULA, $cell->getDataType());
         self::assertSame(['t' => 'array', 'ref' => $expectedRange], $cell->getFormulaAttributes());
-        self::assertSame($expectedFormula, strtoupper($cell->getValue()));
+        self::assertSame($expectedFormula, strtoupper($cell->getValueString()));
         Calculation::getInstance($spreadsheet)->setInstanceArrayReturnType(Calculation::RETURN_ARRAY_AS_ARRAY);
         $worksheet->calculateArrays();
         $cell = $worksheet->getCell($cellAddress);

tests/PhpSpreadsheetTests/Reader/Ods/ArrayFormulaTest.php

@@ -17,7 +17,7 @@ public function testArrayFormulaReader(): void
 
         self::assertSame(DataType::TYPE_FORMULA, $sheet->getCell('B1')->getDataType());
         self::assertSame(['t' => 'array', 'ref' => 'B1:B3'], $sheet->getCell('B1')->getFormulaAttributes());
-        self::assertSame('=CONCATENATE(A1:A3,"-",C1:C3)', strtoupper($sheet->getCell('B1')->getValue()));
+        self::assertSame('=CONCATENATE(A1:A3,"-",C1:C3)', strtoupper($sheet->getCell('B1')->getValueString()));
         self::assertSame('a-1', $sheet->getCell('B1')->getOldCalculatedValue());
         self::assertSame('b-2', $sheet->getCell('B2')->getValue());
         self::assertSame('c-3', $sheet->getCell('B3')->getValue());

tests/PhpSpreadsheetTests/Reader/Xml/ArrayFormulaTest.php

@@ -268,7 +268,9 @@ public function testManyArraysOutput(): void
     {
         $json = file_get_contents('tests/data/Writer/XLSX/ArrayFunctions2.json');
         self::assertNotFalse($json);
-        $this->trn = json_decode($json, true);
+        $trn = json_decode($json, true);
+        self::assertIsArray($trn);
+        $this->trn = $trn;
         $spreadsheet = new Spreadsheet();
         Calculation::getInstance($spreadsheet)->setInstanceArrayReturnType(Calculation::RETURN_ARRAY_AS_ARRAY);