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, all the remaining changes will be in src/Calculation.

Author: oleibman

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(null|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);