Better Definitions for Mixed Parameters and Values Part 1 of Many

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.

Executable code change is to add 2 new methods to Cell - `getValueString` and `getCalculatedValueString`, which are the same as the methods without the String suffix, except that they always return a string result. These are invoked at several places in the code where it makes sense, in particular by Writer code.

Author: oleibman

src/PhpSpreadsheet/Calculation/Engineering/ConvertUOM.php

@@ -27,7 +27,7 @@ class ConvertUOM
     /**
      * Details of the Units of measure that can be used in CONVERTUOM().
      *
-     * @var mixed[]
+     * @var array<string, array{Group: string, 'Unit Name': string, AllowPrefix: bool}>
      */
     private static array $conversionUnits = [
         // Weight and Mass
@@ -201,7 +201,7 @@ class ConvertUOM
     /**
      * Details of the Multiplier prefixes that can be used with Units of Measure in CONVERTUOM().
      *
-     * @var mixed[]
+     * @var array<string, array{multiplier: float, name: string}>
      */
     private static array $conversionMultipliers = [
         'Y' => ['multiplier' => 1E24, 'name' => 'yotta'],
@@ -230,7 +230,7 @@ class ConvertUOM
     /**
      * Details of the Multiplier prefixes that can be used with Units of Measure in CONVERTUOM().
      *
-     * @var mixed[]
+     ** @var array<string, array{multiplier: float|int, name: string}>
      */
     private static array $binaryConversionMultipliers = [
         'Yi' => ['multiplier' => 2 ** 80, 'name' => 'yobi'],
@@ -246,7 +246,7 @@ class ConvertUOM
     /**
      * Details of the Units of measure conversion factors, organised by group.
      *
-     * @var mixed[]
+     * @var array<string, array<string, float>>
      */
     private static array $unitConversions = [
         // Conversion uses gram (g) as an intermediate unit

src/PhpSpreadsheet/Calculation/MathTrig/Arabic.php

@@ -53,7 +53,7 @@ private static function calculateArabic(array $roman, int &$sum = 0, int $subtra
      * Excel Function:
      *        ARABIC(text)
      *
-     * @param mixed $roman Should be a string, or can be an array of strings
+     * @param string|string[] $roman Should be a string, or can be an array of strings
      *
      * @return array|int|string the arabic numberal contrived from the roman numeral
      *         If an array of numbers is passed as the argument, then the returned result will also be an array

src/PhpSpreadsheet/Calculation/TextData/Format.php

@@ -56,6 +56,7 @@ public static function DOLLAR(mixed $value = 0, mixed $decimals = 2)
             if ($value < 0) {
                 $round = 0 - $round;
             }
+            /** @var float|int|string */
             $value = MathTrig\Round::multiple($value, $round);
         }
         $mask = "{$mask};-{$mask}";
@@ -129,6 +130,7 @@ public static function TEXTFORMAT(mixed $value, mixed $format): array|string
         if (!is_numeric($value) && Date::isDateTimeFormatCode($format)) {
             $value1 = DateTimeExcel\DateValue::fromString($value);
             $value2 = DateTimeExcel\TimeValue::fromString($value);
+            /** @var float|int|string */
             $value = (is_numeric($value1) && is_numeric($value2)) ? ($value1 + $value2) : (is_numeric($value1) ? $value2 : $value1);
         }
 

src/PhpSpreadsheet/Cell/Cell.php

@@ -175,6 +175,13 @@ public function getValue(): mixed
         return $this->value;
     }
 
+    public function getValueString(): string
+    {
+        $value = $this->value;
+
+        return ($value === '' || is_scalar($value) || $value instanceof Stringable) ? "$value" : '';
+    }
+
     /**
      * Get cell value with formatting.
      */
@@ -336,6 +343,16 @@ private function convertDateTimeInt(mixed $result): mixed
         return $result;
     }
 
+    /**
+     * Get calculated cell value converted to string.
+     */
+    public function getCalculatedValueString(): string
+    {
+        $value = $this->getCalculatedValue();
+
+        return ($value === '' || is_scalar($value) || $value instanceof Stringable) ? "$value" : '';
+    }
+
     /**
      * Get calculated cell value.
      *

src/PhpSpreadsheet/Shared/Font.php

@@ -695,8 +695,10 @@ private static function findFontFile(string $startDirectory, string $desiredFont
                     $it,
                     RecursiveIteratorIterator::LEAVES_ONLY,
                     RecursiveIteratorIterator::CATCH_GET_CHILD
-                ) as $file
+                ) as $filex
             ) {
+                /** @var string */
+                $file = $filex;
                 if (basename($file) === $desiredFont) {
                     $fontPath = $file;
 

src/PhpSpreadsheet/Shared/StringHelper.php

@@ -346,7 +346,7 @@ public static function formatNumber(float|int|string|null $numericValue): string
      * see OpenOffice.org's Documentation of the Microsoft Excel File Format, sect. 2.5.3.
      *
      * @param string $textValue UTF-8 encoded string
-     * @param mixed[] $arrcRuns Details of rich text runs in $value
+     * @param array<int, array{strlen: int, fontidx: int}> $arrcRuns Details of rich text runs in $value
      */
     public static function UTF8toBIFF8UnicodeShort(string $textValue, array $arrcRuns = []): string
     {

src/PhpSpreadsheet/Style/NumberFormat.php

@@ -2,6 +2,8 @@
 
 namespace PhpOffice\PhpSpreadsheet\Style;
 
+use PhpOffice\PhpSpreadsheet\RichText\RichText;
+
 class NumberFormat extends Supervisor
 {
     // Pre-defined formats
@@ -453,7 +455,7 @@ public function getHashCode(): string
     /**
      * Convert a value in a pre-defined format to a PHP string.
      *
-     * @param mixed $value Value to format
+     * @param null|bool|float|int|RichText|string $value Value to format
      * @param string $format Format code: see = self::FORMAT_* for predefined values;
      *                          or can be any valid MS Excel custom format string
      * @param ?array $callBack Callback function for additional formatting of string

src/PhpSpreadsheet/Style/NumberFormat/Formatter.php

@@ -42,6 +42,7 @@ private static function splitFormatComparison(
         };
     }
 
+    /** @param float|int|string $value value to be formatted */
     private static function splitFormatForSectionSelection(array $sections, mixed $value): array
     {
         // Extract the relevant section depending on whether number is positive, negative, or zero?

src/PhpSpreadsheet/Style/NumberFormat/FractionFormatter.php

@@ -6,6 +6,7 @@
 
 class FractionFormatter extends BaseFormatter
 {
+    /** @param null|bool|float|int|string $value  value to be formatted */
     public static function format(mixed $value, string $format): string
     {
         $format = self::stripQuotes($format);

src/PhpSpreadsheet/Worksheet/Table.php

@@ -178,7 +178,7 @@ private function updateStructuredReferencesInCells(Worksheet $worksheet, string
         foreach ($worksheet->getCoordinates(false) as $coordinate) {
             $cell = $worksheet->getCell($coordinate);
             if ($cell->getDataType() === DataType::TYPE_FORMULA) {
-                $formula = $cell->getValue();
+                $formula = $cell->getValueString();
                 if (preg_match($pattern, $formula) === 1) {
                     $formula = preg_replace($pattern, "{$newName}[", $formula);
                     $cell->setValueExplicit($formula, DataType::TYPE_FORMULA);