Merge pull request #4016 from oleibman/stan9a

Better Definitions for Mixed Parameters and Values Part 1 of Many
PHPOffice · May 9, 2024 · d38b7cb · d38b7cb
2 parents c56a583 + 8d5577a
commit d38b7cb
Show file tree

Hide file tree

Showing 20 changed files with 225 additions and 183 deletions.
diff --git a/src/PhpSpreadsheet/Calculation/Engineering/ConvertUOM.php b/src/PhpSpreadsheet/Calculation/Engineering/ConvertUOM.php
diff --git a/src/PhpSpreadsheet/Calculation/MathTrig/Arabic.php b/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

diff --git a/src/PhpSpreadsheet/Calculation/TextData/Format.php b/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);
         }
 

diff --git a/src/PhpSpreadsheet/Cell/Cell.php b/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.
      *

diff --git a/src/PhpSpreadsheet/Shared/Font.php b/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;
 

diff --git a/src/PhpSpreadsheet/Shared/StringHelper.php b/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
     {

diff --git a/src/PhpSpreadsheet/Style/NumberFormat.php b/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

diff --git a/src/PhpSpreadsheet/Style/NumberFormat/Formatter.php b/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?

diff --git a/src/PhpSpreadsheet/Style/NumberFormat/FractionFormatter.php b/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);

diff --git a/src/PhpSpreadsheet/Worksheet/Table.php b/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);

diff --git a/src/PhpSpreadsheet/Worksheet/Table/Column.php b/src/PhpSpreadsheet/Worksheet/Table/Column.php
@@ -216,7 +216,7 @@ private static function updateStructuredReferencesInCells(Worksheet $worksheet,
         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, "[$1{$newTitle}]", $formula);
                     $cell->setValueExplicit($formula, DataType::TYPE_FORMULA);

diff --git a/src/PhpSpreadsheet/Worksheet/Worksheet.php b/src/PhpSpreadsheet/Worksheet/Worksheet.php
@@ -2862,7 +2862,7 @@ public function rangeToArray(
      * @param bool $ignoreHidden False - Return values for rows/columns even if they are defined as hidden.
      *                            True - Don't return values for rows/columns that are defined as hidden.
      *
-     * @return Generator
+     * @return Generator<array>
      */
     public function rangeToArrayYieldRows(
         string $range,

diff --git a/src/PhpSpreadsheet/Writer/Csv.php b/src/PhpSpreadsheet/Writer/Csv.php
@@ -4,6 +4,7 @@
 
 use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use Stringable;
 
 class Csv extends BaseWriter
 {
@@ -246,6 +247,8 @@ public function getEnclosureRequired(): bool
 
     /**
      * Convert boolean to TRUE/FALSE; otherwise return element cast to string.
+     *
+     * @param null|bool|float|int|string|Stringable $element element to be converted
      */
     private static function elementToString(mixed $element): string
     {
@@ -270,6 +273,7 @@ private function writeLine($fileHandle, array $values): void
         // Build the line
         $line = '';
 
+        /** @var null|bool|float|int|string|Stringable $element */
         foreach ($values as $element) {
             $element = self::elementToString($element);
             // Add delimiter

diff --git a/src/PhpSpreadsheet/Writer/Html.php b/src/PhpSpreadsheet/Writer/Html.php
@@ -1310,10 +1310,11 @@ private function generateRowCellDataValue(Worksheet $worksheet, Cell $cell, stri
             $cellData .= $this->generateRowCellDataValueRich($cell->getValue());
         } else {
             $origData = $this->preCalculateFormulas ? $cell->getCalculatedValue() : $cell->getValue();
+            $origData2 = $this->preCalculateFormulas ? $cell->getCalculatedValueString() : $cell->getValueString();
             $formatCode = $worksheet->getParentOrThrow()->getCellXfByIndex($cell->getXfIndex())->getNumberFormat()->getFormatCode();
 
             $cellData = NumberFormat::toFormattedString(
-                $origData ?? '',
+                $origData2,
                 $formatCode ?? NumberFormat::FORMAT_GENERAL,
                 [$this, 'formatColor']
             );

diff --git a/src/PhpSpreadsheet/Writer/Ods/Content.php b/src/PhpSpreadsheet/Writer/Ods/Content.php
@@ -209,8 +209,8 @@ private function writeCells(XMLWriter $objWriter, RowCellIterator $cells): void
             switch ($cell->getDataType()) {
                 case DataType::TYPE_BOOL:
                     $objWriter->writeAttribute('office:value-type', 'boolean');
-                    $objWriter->writeAttribute('office:value', $cell->getValue());
-                    $objWriter->writeElement('text:p', $cell->getValue());
+                    $objWriter->writeAttribute('office:value', $cell->getValueString());
+                    $objWriter->writeElement('text:p', $cell->getValueString());
 
                     break;
                 case DataType::TYPE_ERROR:
@@ -221,15 +221,15 @@ private function writeCells(XMLWriter $objWriter, RowCellIterator $cells): void
 
                     break;
                 case DataType::TYPE_FORMULA:
-                    $formulaValue = $cell->getValue();
+                    $formulaValue = $cell->getValueString();
                     if ($this->getParentWriter()->getPreCalculateFormulas()) {
                         try {
-                            $formulaValue = $cell->getCalculatedValue();
+                            $formulaValue = $cell->getCalculatedValueString();
                         } catch (CalculationException $e) {
                             // don't do anything
                         }
                     }
-                    $objWriter->writeAttribute('table:formula', $this->formulaConvertor->convertFormula($cell->getValue()));
+                    $objWriter->writeAttribute('table:formula', $this->formulaConvertor->convertFormula($cell->getValueString()));
                     if (is_numeric($formulaValue)) {
                         $objWriter->writeAttribute('office:value-type', 'float');
                     } else {
@@ -241,8 +241,8 @@ private function writeCells(XMLWriter $objWriter, RowCellIterator $cells): void
                     break;
                 case DataType::TYPE_NUMERIC:
                     $objWriter->writeAttribute('office:value-type', 'float');
-                    $objWriter->writeAttribute('office:value', $cell->getValue());
-                    $objWriter->writeElement('text:p', $cell->getValue());
+                    $objWriter->writeAttribute('office:value', $cell->getValueString());
+                    $objWriter->writeElement('text:p', $cell->getValueString());
 
                     break;
                 case DataType::TYPE_INLINE:
@@ -251,7 +251,7 @@ private function writeCells(XMLWriter $objWriter, RowCellIterator $cells): void
                     $objWriter->writeAttribute('office:value-type', 'string');
                     $url = $cell->getHyperlink()->getUrl();
                     if (empty($url)) {
-                        $objWriter->writeElement('text:p', $cell->getValue());
+                        $objWriter->writeElement('text:p', $cell->getValueString());
                     } else {
                         $objWriter->startElement('text:p');
                         $objWriter->startElement('text:a');
@@ -262,7 +262,7 @@ private function writeCells(XMLWriter $objWriter, RowCellIterator $cells): void
                         }
                         $objWriter->writeAttribute('xlink:href', $url);
                         $objWriter->writeAttribute('xlink:type', 'simple');
-                        $objWriter->text($cell->getValue());
+                        $objWriter->text($cell->getValueString());
                         $objWriter->endElement(); // text:a
                         $objWriter->endElement(); // text:p
                     }

diff --git a/src/PhpSpreadsheet/Writer/Xlsx/Table.php b/src/PhpSpreadsheet/Writer/Xlsx/Table.php
@@ -80,7 +80,7 @@ public function writeTable(WorksheetTable $table, int $tableRef): string
 
             $objWriter->startElement('tableColumn');
             $objWriter->writeAttribute('id', (string) ($offset + 1));
-            $objWriter->writeAttribute('name', $table->getShowHeaderRow() ? $cell->getValue() : 'Column' . ($offset + 1));
+            $objWriter->writeAttribute('name', $table->getShowHeaderRow() ? $cell->getValueString() : ('Column' . ($offset + 1)));
 
             if ($table->getShowTotalsRow()) {
                 if ($column->getTotalsRowLabel()) {

diff --git a/tests/PhpSpreadsheetTests/Calculation/Functions/Engineering/ConvertUoMTest.php b/tests/PhpSpreadsheetTests/Calculation/Functions/Engineering/ConvertUoMTest.php
@@ -18,31 +18,37 @@ class ConvertUoMTest extends TestCase
     public function testGetConversionGroups(): void
     {
         $result = ConvertUOM::getConversionCategories();
-        self::assertIsArray($result);
+        self::assertContains('Weight and Mass', $result);
     }
 
     public function testGetConversionGroupUnits(): void
     {
         $result = ConvertUOM::getConversionCategoryUnits();
-        self::assertIsArray($result);
+        self::assertArrayHasKey('Speed', $result);
+        self::assertIsArray($result['Speed']);
+        self::assertContains('mph', $result['Speed']);
     }
 
     public function testGetConversionGroupUnitDetails(): void
     {
         $result = ConvertUOM::getConversionCategoryUnitDetails();
-        self::assertIsArray($result);
+        self::assertArrayHasKey('Information', $result);
+        self::assertIsArray($result['Information']);
+        self::assertContains(['unit' => 'byte', 'description' => 'Byte'], $result['Information']);
     }
 
     public function testGetConversionMultipliers(): void
     {
         $result = ConvertUOM::getConversionMultipliers();
-        self::assertIsArray($result);
+        self::assertArrayHasKey('k', $result);
+        self::assertSame(['multiplier' => 1000.0, 'name' => 'kilo'], $result['k']);
     }
 
     public function testGetBinaryConversionMultipliers(): void
     {
         $result = ConvertUOM::getBinaryConversionMultipliers();
-        self::assertIsArray($result);
+        self::assertArrayHasKey('ki', $result);
+        self::assertSame(['multiplier' => 1024, 'name' => 'kibi'], $result['ki']);
     }
 
     /**

diff --git a/tests/PhpSpreadsheetTests/Cell/CellAddressTest.php b/tests/PhpSpreadsheetTests/Cell/CellAddressTest.php
@@ -84,7 +84,7 @@ public function testCreateFromColumnAndRow(
     /**
      * @dataProvider providerCreateFromColumnRowException
      */
-    public function testCreateFromColumnRowException(mixed $columnId, mixed $rowId): void
+    public function testCreateFromColumnRowException(int|string $columnId, int|string $rowId): void
     {
         $this->expectException(Exception::class);
         $this->expectExceptionMessage('Row and Column Ids must be positive integer values');

diff --git a/tests/PhpSpreadsheetTests/Document/PropertiesTest.php b/tests/PhpSpreadsheetTests/Document/PropertiesTest.php
@@ -153,7 +153,7 @@ public function testSetManager(): void
     /**
      * @dataProvider providerCustomProperties
      */
-    public function testSetCustomProperties(mixed $expectedType, mixed $expectedValue, string $propertyName, mixed $propertyValue, ?string $propertyType = null): void
+    public function testSetCustomProperties(mixed $expectedType, mixed $expectedValue, string $propertyName, null|bool|float|int|string $propertyValue, ?string $propertyType = null): void
     {
         if ($propertyType === null) {
             $this->properties->setCustomProperty($propertyName, $propertyValue);

diff --git a/tests/PhpSpreadsheetTests/Style/NumberFormatTest.php b/tests/PhpSpreadsheetTests/Style/NumberFormatTest.php
@@ -26,6 +26,8 @@ protected function tearDown(): void
 
     /**
      * @dataProvider providerNumberFormat
+     *
+     * @param null|bool|float|int|string $args string to be formatted
      */
     public function testFormatValueWithMask(mixed $expectedResult, mixed ...$args): void
     {
@@ -40,6 +42,8 @@ public static function providerNumberFormat(): array
 
     /**
      * @dataProvider providerNumberFormatFractions
+     *
+     * @param null|bool|float|int|string $args string to be formatted
      */
     public function testFormatValueWithMaskFraction(mixed $expectedResult, mixed ...$args): void
     {
@@ -54,6 +58,8 @@ public static function providerNumberFormatFractions(): array
 
     /**
      * @dataProvider providerNumberFormatDates
+     *
+     * @param null|bool|float|int|string $args string to be formatted
      */
     public function testFormatValueWithMaskDate(mixed $expectedResult, mixed ...$args): void
     {