Make Explicit Array Return Type When Tests Require It

When the Dynamic Array PR PHPOffice#3962 was introduced, it left the default as Return Array as Value. At some point, the default should be changed to Return Array as Array. This would, of course, be a breaking change, one which will not be part of Release 4. However, it will possibly be part of Release 5.

Rather than relying on the default setting, this PR explicitly sets Return Array as Value when tests require that setting. This will make it easier to identify potential breaks when the default is changed. The entire test suite will now succeed with either setting as default.

In making these changes, a few minor problems were discovered with how Array as Array is handled. These are fixed with this PR.

Author: oleibman

samples/LookupRef/COLUMN.php

@@ -1,5 +1,6 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
 
 require __DIR__ . '/../Header.php';
@@ -8,6 +9,10 @@
 
 // Create new PhpSpreadsheet object
 $spreadsheet = new Spreadsheet();
+$calculation = Calculation::getInstance($spreadsheet);
+$calculation->setInstanceArrayReturnType(
+    Calculation::RETURN_ARRAY_AS_VALUE
+);
 $worksheet = $spreadsheet->getActiveSheet();
 
 $worksheet->getCell('A1')->setValue('=COLUMN(C13)');

src/PhpSpreadsheet/Calculation/Calculation.php

@@ -4882,17 +4882,18 @@ private function processTokenStack(mixed $tokens, ?string $cellID = null, ?Cell
                             }
                             $result = $operand1;
                         } else {
-                            // In theory, we should truncate here.
-                            // But I can't figure out a formula
-                            // using the concatenation operator
-                            // with literals that fits in 32K,
-                            // so I don't think we can overflow here.
                             if (Information\ErrorValue::isError($operand1)) {
                                 $result = $operand1;
                             } elseif (Information\ErrorValue::isError($operand2)) {
                                 $result = $operand2;
                             } else {
-                                $result = self::FORMULA_STRING_QUOTE . str_replace('""', self::FORMULA_STRING_QUOTE, self::unwrapResult($operand1) . self::unwrapResult($operand2)) . self::FORMULA_STRING_QUOTE;
+                                $result = str_replace('""', self::FORMULA_STRING_QUOTE, self::unwrapResult($operand1) . self::unwrapResult($operand2));
+                                $result = Shared\StringHelper::substring(
+                                    $result,
+                                    0,
+                                    DataType::MAX_STRING_LENGTH
+                                );
+                                $result = self::FORMULA_STRING_QUOTE . $result . self::FORMULA_STRING_QUOTE;
                             }
                         }
                         $this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($result));
@@ -5041,6 +5042,9 @@ private function processTokenStack(mixed $tokens, ?string $cellID = null, ?Cell
                     while (is_array($cellValue)) {
                         $cellValue = array_shift($cellValue);
                     }
+                    if (is_string($cellValue)) {
+                        $cellValue = preg_replace('/"/', '""', $cellValue);
+                    }
                     $this->debugLog->writeDebugLog('Scalar Result for cell %s is %s', $cellRef, $this->showTypeDetails($cellValue));
                 }
                 $this->processingAnchorArray = false;

src/PhpSpreadsheet/Calculation/Financial/CashFlow/Single.php

@@ -77,13 +77,13 @@ public static function periods(mixed $rate, mixed $presentValue, mixed $futureVa
      *
      * Calculates the interest rate required for an investment to grow to a specified future value .
      *
-     * @param array|float $periods The number of periods over which the investment is made
-     * @param array|float $presentValue Present Value
-     * @param array|float $futureValue Future Value
+     * @param mixed $periods The number of periods over which the investment is made, expect array|float
+     * @param mixed $presentValue Present Value, expect array|float
+     * @param mixed $futureValue Future Value, expect array|float
      *
      * @return float|string Result, or a string containing an error
      */
-    public static function interestRate(array|float $periods = 0.0, array|float $presentValue = 0.0, array|float $futureValue = 0.0): string|float
+    public static function interestRate(mixed $periods = 0.0, mixed $presentValue = 0.0, mixed $futureValue = 0.0): string|float
     {
         $periods = Functions::flattenSingleValue($periods);
         $presentValue = Functions::flattenSingleValue($presentValue);

src/PhpSpreadsheet/Calculation/Financial/CashFlow/Variable/NonPeriodic.php

@@ -23,14 +23,14 @@ class NonPeriodic
      * Excel Function:
      *        =XIRR(values,dates,guess)
      *
-     * @param float[] $values     A series of cash flow payments
+     * @param mixed $values     A series of cash flow payments, expecting float[]
      *                                The series of values must contain at least one positive value & one negative value
      * @param mixed[] $dates      A series of payment dates
      *                                The first payment date indicates the beginning of the schedule of payments
      *                                All other dates must be later than this date, but they may occur in any order
      * @param mixed $guess        An optional guess at the expected answer
      */
-    public static function rate(array $values, array $dates, mixed $guess = self::DEFAULT_GUESS): float|string
+    public static function rate(mixed $values, mixed $dates, mixed $guess = self::DEFAULT_GUESS): float|string
     {
         $rslt = self::xirrPart1($values, $dates);
         if ($rslt !== '') {
@@ -106,18 +106,18 @@ public static function rate(array $values, array $dates, mixed $guess = self::DE
      * Excel Function:
      *        =XNPV(rate,values,dates)
      *
-     * @param array|float $rate the discount rate to apply to the cash flows
-     * @param float[] $values A series of cash flows that corresponds to a schedule of payments in dates.
+     * @param mixed $rate the discount rate to apply to the cash flows, expect array|float
+     * @param mixed $values A series of cash flows that corresponds to a schedule of payments in dates, expecting floag[].
      *                          The first payment is optional and corresponds to a cost or payment that occurs
      *                              at the beginning of the investment.
      *                          If the first value is a cost or payment, it must be a negative value.
      *                             All succeeding payments are discounted based on a 365-day year.
      *                          The series of values must contain at least one positive value and one negative value.
-     * @param mixed[] $dates A schedule of payment dates that corresponds to the cash flow payments.
+     * @param mixed $dates A schedule of payment dates that corresponds to the cash flow payments, expecting mixed[].
      *                         The first payment date indicates the beginning of the schedule of payments.
      *                         All other dates must be later than this date, but they may occur in any order.
      */
-    public static function presentValue(array|float $rate, array $values, array $dates): float|string
+    public static function presentValue(mixed $rate, mixed $values, mixed $dates): float|string
     {
         return self::xnpvOrdered($rate, $values, $dates, true);
     }

src/PhpSpreadsheet/Calculation/LookupRef/Matrix.php

@@ -82,6 +82,15 @@ public static function index(mixed $matrix, mixed $rowNum = 0, mixed $columnNum
 
         $rowNum = $rowNum ?? 0;
         $columnNum = $columnNum ?? 0;
+        if (is_scalar($matrix)) {
+            if ($rowNum === 0 || $rowNum === 1) {
+                if ($columnNum === 0 || $columnNum === 1) {
+                    if ($columnNum === 1 || $rowNum === 1) {
+                        return $matrix;
+                    }
+                }
+            }
+        }
 
         try {
             $rowNum = LookupRefValidations::validatePositiveInt($rowNum);

src/PhpSpreadsheet/Cell/Cell.php

@@ -408,9 +408,6 @@ public function getCalculatedValue(bool $resetLog = true): mixed
         $oldAttributesT = $oldAttributes['t'] ?? '';
         $coordinate = $this->getCoordinate();
         $oldAttributesRef = $oldAttributes['ref'] ?? $coordinate;
-        if (!str_contains($oldAttributesRef, ':')) {
-            $oldAttributesRef .= ":$oldAttributesRef";
-        }
         $originalValue = $this->value;
         $originalDataType = $this->dataType;
         $this->formulaAttributes = [];
@@ -434,6 +431,14 @@ public function getCalculatedValue(bool $resetLog = true): mixed
                         $result = array_shift($result);
                     }
                 }
+                if (
+                    !is_array($result)
+                    && $calculation->getInstanceArrayReturnType() === Calculation::RETURN_ARRAY_AS_ARRAY
+                    && $oldAttributesT === 'array'
+                    && ($oldAttributesRef === $coordinate || $oldAttributesRef === "$coordinate:$coordinate")
+                ) {
+                    $result = [$result];
+                }
                 // if return_as_array for formula like '=sheet!cell'
                 if (is_array($result) && count($result) === 1) {
                     $resultKey = array_keys($result)[0];
@@ -560,6 +565,8 @@ public function getCalculatedValue(bool $resetLog = true): mixed
             SharedDate::setExcelCalendar($currentCalendar);
 
             if ($result === Functions::NOT_YET_IMPLEMENTED) {
+                $this->formulaAttributes = $oldAttributes;
+
                 return $this->calculatedValue; // Fallback if calculation engine does not support the formula.
             }
 

src/PhpSpreadsheet/Writer/Xlsx/Worksheet.php

@@ -1498,6 +1498,9 @@ private function writeCellFormula(XMLWriter $objWriter, string $cellValue, Cell
 
         if (isset($attributes['ref'])) {
             $ref = $this->parseRef($coordinate, $attributes['ref']);
+            if ($ref === "$coordinate:$coordinate") {
+                $ref = $coordinate;
+            }
         } else {
             $ref = $coordinate;
         }

tests/PhpSpreadsheetTests/Calculation/ArrayFormulaTest.php

@@ -62,6 +62,10 @@ public static function providerArrayFormulae(): array
     public function testArrayFormulaUsingCells(): void
     {
         $spreadsheet = new Spreadsheet();
+        $calculation = Calculation::getInstance($spreadsheet);
+        $calculation->setInstanceArrayReturnType(
+            Calculation::RETURN_ARRAY_AS_VALUE
+        );
         $sheet = $spreadsheet->getActiveSheet();
         $sheet->getCell('A4')->setValue(-3);
         $sheet->getCell('B4')->setValue(4);

tests/PhpSpreadsheetTests/Calculation/CalculationLoggingTest.php

@@ -42,6 +42,10 @@ public function testFormulaWithLogging(): void
     public function testFormulaWithMultipleCellLogging(): void
     {
         $spreadsheet = new Spreadsheet();
+        $calculation = Calculation::getInstance($spreadsheet);
+        $calculation->setInstanceArrayReturnType(
+            Calculation::RETURN_ARRAY_AS_VALUE
+        );
         $sheet = $spreadsheet->getActiveSheet();
 
         $sheet->fromArray(

tests/PhpSpreadsheetTests/Calculation/FormulaAsStringTest.php

@@ -4,15 +4,21 @@
 
 namespace PhpOffice\PhpSpreadsheetTests\Calculation;
 
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
 class FormulaAsStringTest extends TestCase
 {
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerFunctionsAsString')]
+    #[DataProvider('providerFunctionsAsString')]
     public function testFunctionsAsString(mixed $expectedResult, string $formula): void
     {
         $spreadsheet = new Spreadsheet();
+        $calculation = Calculation::getInstance($spreadsheet);
+        $calculation->setInstanceArrayReturnType(
+            Calculation::RETURN_ARRAY_AS_VALUE
+        );
         $workSheet = $spreadsheet->getActiveSheet();
         $workSheet->setCellValue('A1', 10);
         $workSheet->setCellValue('A2', 20);