Mostly Docs and Tests

Also support for Xml format.

Author: oleibman

docs/topics/recipes.md

@@ -376,7 +376,7 @@ $value = $spreadsheet->getActiveSheet()->getCell('B8')->getCalculatedValue();
 ### Array Formulas
 
 With version 2.0.3 of PhpSpreadsheet, we've introduced support for Excel "array formulas".
-It is an opt-in feature. You need to enable it with the following code:
+**It is an opt-in feature.** You need to enable it with the following code:
 ```php
 \PhpOffice\PhpSpreadsheet\Calculation\Calculation::setArrayReturnType(
     \PhpOffice\PhpSpreadsheet\Calculation\Calculation::RETURN_ARRAY_AS_ARRAY);
@@ -405,15 +405,16 @@ However, we could have specified an alternative formula to calculate that result
 
 ![12-CalculationEngine-Array-Formula.png](./images/12-CalculationEngine-Array-Formula.png)
 
-Entering the formula `=SUM(B2:B6*C2:C6)` will calculate the same result; but because it's using arrays, we need to enter it as an "array formula". In MS Excel itself, we'd do this by using `Shift-Ctrl-Enter` rather than simply `Enter` when we define the formula in the formula edit box. MS Excel then shows that this is an array formula in the formula edit box by wrapping it in the `{}` braces (you don't enter these in the formula yourself; MS Excel does it).
-In recent releases of Excel, Shift-Ctrl-Enter is not required, and Excel does not add the braces.
-PhpSpreadsheet will attempt to behave like the recent releases.
+Entering the formula `=SUM(B2:B6*C2:C6)` will calculate the same result; but because it's using arrays, we need to enter it as an "array formula". In MS Excel itself, we'd do this by using `Ctrl-Shift-Enter` rather than simply `Enter` when we define the formula in the formula edit box. MS Excel then shows that this is an array formula in the formula edit box by wrapping it in the `{}` braces (you don't enter these in the formula yourself; MS Excel does it).
+
+**In recent releases of Excel, Ctrl-Shift-Enter is not required, and Excel does not add the braces.
+PhpSpreadsheet will attempt to behave like the recent releases.**
 
 Or to identify the biggest increase in like-for-like sales from one month to the next:
 
 ![12-CalculationEngine-Array-Formula-3.png](./images/12-CalculationEngine-Array-Formula-3.png)
 ```php
-$spreadsheet->getActiveSheet()->setCellValue('F1','=MAX(B2:B6-C2:C6)', true);
+$spreadsheet->getActiveSheet()->setCellValue('F1','=MAX(B2:B6-C2:C6)');
 ```
 Which tells us that the biggest increase in sales between December and January was 30 more (in this case, 30 more Lemons).
 
@@ -424,8 +425,8 @@ As an example, consider transposing a grid of data: MS Excel provides the `TRANS
 
 ![12-CalculationEngine-Array-Formula-2.png](./images/12-CalculationEngine-Array-Formula-2.png)
 
-When we do this in MS Excel, we need to indicate ___all___ the cells that will contain the transposed data from cells `A1` to `D7`. We do this by selecting the cells where we want to display our transposed data either by holding the left mouse button down while we move with the mouse, or pressing `Shift` and using the arrow keys.
-Once we've selected all the cells to hold our data, then we enter the formula `TRANSPOSE(A1:D7)` in the formula edit box, remembering to use `Shift-Ctrl-Enter` to tell MS Excel that this is an array formula.
+When we do this in MS Excel, we used to need to indicate ___all___ the cells that will contain the transposed data from cells `A1` to `D7`. We do this by selecting the cells where we want to display our transposed data either by holding the left mouse button down while we move with the mouse, or pressing `Shift` and using the arrow keys.
+Once we've selected all the cells to hold our data, then we enter the formula `TRANSPOSE(A1:D7)` in the formula edit box, remembering to use `Ctrl-Shift-Enter` to tell MS Excel that this is an array formula. In recent Excel, you can just enter `=TRANSPOSE(A1:D7)` into cell A10.
 
 Note also that we still set this as the formula for the top-left cell of that range, cell `A10`.
 
@@ -434,66 +435,40 @@ Simply setting an array formula in a cell and specifying the range won't populat
 $spreadsheet->getActiveSheet()
     ->setCellValue(
         'A10',
-        '=SEQUENCE(3,3)',
-        true,
-        'A1:C3'
+        '=SEQUENCE(3,3)'
     );
-
 // Will return a null, because the formula for A1 hasn't been calculated to populate the spillage area 
 $result = $spreadsheet->getActiveSheet()->getCell('C3')->getValue();
 ```
 To do that, we need to retrieve the calculated value for the cell.
 ```php
-$spreadsheet->getActiveSheet()
-    ->setCellValue(
-        'A10',
-        '=SEQUENCE(3,3)',
-        true,
-        'A1:C3'
-    );
-
 $spreadsheet->getActiveSheet()->getCell('A1')->getCalculatedValue();
-
 // Will return 9, because the formula for A1 has now been calculated, and the spillage area is populated 
 $result = $spreadsheet->getActiveSheet()->getCell('C3')->getValue();
 ```
-When we call `getCalculatedValue()` for a cell that contains an array formula, PhpSpreadsheet returns the single value that would appear in that cell in MS Excel.
+If returning arrays has been enabled, `getCalculatedValue` will return an array when appropriate, and will populate the spill range. If returning arrays has not been enabled, when we call `getCalculatedValue()` for a cell that contains an array formula, PhpSpreadsheet will return the single value from the topmost leftmost cell, and will leave other cells unchanged.
 ```php
 // Will return integer 1, the value for that cell within the array
 $a1result = $spreadsheet->getActiveSheet()->getCell('A1')->getCalculatedValue();
 ```
 
-If we want to return the full array, then we need to call `getCalculatedValue()` with an additional argument, a boolean `true` to return the value as an array.
-```php
-// Will return an array [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
-$a1result = $spreadsheet->getActiveSheet()->getCell('A1')->getCalculatedValue(true);
-```
-
 ---
 
 Excel365 introduced a number of new functions that return arrays of results.
 These include the `UNIQUE()`, `SORT()`, `SORTBY()`, `FILTER()`, `SEQUENCE()` and `RANDARRAY()` functions.
 While not all of these have been implemented by the Calculation Engine in PhpSpreadsheet, so they cannot all be calculated within your PHP applications, they can still be read from and written to Xlsx files.
 
-The way these functions are presented in MS Excel itself is slightly different to that of other array functions.
-
 The `SEQUENCE()` function generates a series of values (in this case, starting with `-10` and increasing in steps of `2.5`); and here we're telling the formula to populate a 3x3 grid with these values.
 
 ![12-CalculationEngine-Spillage-Formula.png](./images/12-CalculationEngine-Spillage-Formula.png)
 
-Note that this is visually different to the multi-cell array formulas like `TRANSPOSE()`. When we are positioned in the "spill" range for the grid, MS Excel highlights the area with a blue border; and the formula displayed in the formula editing field isn't wrapped in braces (`{}`).
+Note that this is visually different from using `Ctrl-Shift-Enter` for the formula. When we are positioned in the "spill" range for the grid, MS Excel highlights the area with a blue border; and the formula displayed in the formula editing field isn't wrapped in braces (`{}`).
 
 And if we select any other cell inside the "spill" area other than the top-left cell, the formula in the formula edit field is greyed rather than displayed in black.
 
 ![12-CalculationEngine-Spillage-Formula-2.png](./images/12-CalculationEngine-Spillage-Formula-2.png)
 
-When we enter this formula in MS Excel, we don't need to select the range of cells that it should occupy; nor do we need to enter it using `Ctrl-Shift-Enter`. MS Excel identifies that it is a multi-cell array formula because of the function that it uses, the `SEQUENCE()` function (and if there are nested function calls in the formula, then it must be the outermost functionin the tree).
-
-However, PhpSpreadsheet isn't quite as intelligent (yet) and doesn't parse the formula to identify if it should be treated as an array formula or not; a formula is just a string of characters until it is actually evaluated. If we want to use this function through code, we still need to specify that it is an "array" function with the `$isArrayFormula` argument, and the range of cells that it should cover.
-
-```php
-$spreadsheet->getActiveSheet()->setCellValue('A1','=SEQUENCE(3,3,-10,2.5)', true, 'A1:C3');
-```
+When we enter this formula in MS Excel, we don't need to select the range of cells that it should occupy; nor do we need to enter it using `Ctrl-Shift-Enter`.
 
 ### The Spill Operator
 
@@ -502,19 +477,34 @@ To simplify this, MS Excel has introduced the "Spill" Operator (`#`).
 
 ![12-CalculationEngine-Spillage-Operator.png](./images/12-CalculationEngine-Spillage-Operator.png)
 
-Using our `SEQUENCE()"`example, where the formula cell is `A1` and the result spills across the range `A1:C3`, we can use the Spill operator `A1#` to reference all the cells in that spillage range.
+Using our `SEQUENCE()`example, where the formula cell is `A1` and the result spills across the range `A1:C3`, we can use the Spill operator `A1#` to reference all the cells in that spillage range.
 In this case, we're taking the absolute value of each cell in that range, and adding them together using the `SUM()` function to give us a result of 50. 
 
-PhpSpreadsheet doesn't currently support entry of a formula like this directly; but interally MS Excel implements the Spill Operator as a function (`ANCHORARRAY()`). MS Excel itself doesn't allow you to use this function in a formula, you have to use the "Spill" operator; but PhpSpreadsheet does allow you to use this internal Excel function.
+PhpSpreadsheet supports entry of a formula like this using the Spill operator. Alternatively, MS Excel internally implements the Spill Operator as a function (`ANCHORARRAY()`). MS Excel itself doesn't allow you to use this function in a formula, you have to use the "Spill" operator; but PhpSpreadsheet does allow you to use this internal Excel function. PhpSpreadsheet will convert the spill operator to ANCHORARRAY on write (so it may appear that your formula has changed, but it hasn't really); it is not necessary to convert it back on read.
 
 To create this same function in PhpSpreadsheet, use:
 ```php
-$spreadsheet->getActiveSheet()->setCellValue('D1','=SUM(ABS(ANCHORARRAY(A1)))', true);
+$spreadsheet->getActiveSheet()->setCellValue('D1','=SUM(ABS(ANCHORARRAY(A1)))');
 ```
-Note that this does need to be flagged as an array function with the `$isArrayFormula` argument.
 
 When the file is saved, and opened in MS Excel, it will be rendered correctly.
 
+### The At-sign Operator
+
+If you want to reference just the first cell of an array formula within another formula, you could do so by prefixing it with an at-sign. You can also select the entry in a range which matches the current row in this way; so, if you enter `=@A1:A5` in cell G3, the result will be the value from A3. MS Excel again implements this under the covers by converting to a function SINGLE. PhpSpreadsheet allows the use of the SINGLE function. It does not yet support the at-sign operator, which can have a different meaning in other contexts.
+
+### Updating Cell in Spill Area
+
+Excel prevents you from updating a cell in the spill area. PhpSpreadsheet does not - it seems like it might be quite expensive, needing to reevaluate the entire worksheet with each `setValue`. PhpSpreadsheet does provide a method to be used prior to calling `setValue` if desired.
+```php
+$sheet->setCellValue('A1', '=SORT{7;5;1}');
+$sheet->getCell('A1')->getCalculatedValue(); // populates A1-A3
+$sheet->isCellInSpillRange('A2'); // true
+$sheet->isCellInSpillRange('A3'); // true
+$sheet->isCellInSpillRange('A4'); // false
+$sheet->isCellInSpillRange('A1'); // false
+```
+The last result might be surprising. Excel allows you to alter the formula cell itself, so `isCellInSpillRange` treats the formula cell as not in range. It should also be noted that, if array returns are not enabled, `isCellInSpillRange` will always return `false`.
 
 ## Locale Settings for Formulas
 
@@ -552,7 +542,7 @@ $spreadsheet->getActiveSheet()->setCellValue('B8',$internalFormula);
 ```
 
 Currently, formula translation only translates the function names, the
-constants TRUE and FALSE, and the function argument separators. Cell addressing using R1C1 formatting is not supported.
+constants TRUE and FALSE (and NULL), Excel error messages, and the function argument separators. Cell addressing using R1C1 formatting is not supported.
 
 At present, the following locale settings are supported:
 
@@ -576,6 +566,8 @@ Russian              | русский язык         | ru
 Swedish              | Svenska              | sv
 Turkish              | Türkçe               | tr
 
+If anybody can provide translations for additional languages, particularly Basque (Euskara), Catalan (Català), Croatian (Hrvatski jezik), Galician (Galego), Greek (Ελληνικά), Slovak (Slovenčina) or Slovenian (Slovenščina); please feel free to volunteer your services, and we'll happily show you what is needed to contribute a new language. 
+
 ## Write a newline character "\n" in a cell (ALT+"Enter")
 
 In Microsoft Office Excel you get a line break in a cell by hitting

src/PhpSpreadsheet/Calculation/Internal/ExcelArrayPseudoFunctions.php

@@ -20,7 +20,7 @@ public static function single(string $cellReference, Cell $cell): mixed
             $ourRow = $cell->getRow();
             $firstRow = (int) $matches[3];
             $lastRow = (int) $matches[6];
-            if ($ourRow < $firstRow || $ourRow > $lastRow) {
+            if ($ourRow < $firstRow || $ourRow > $lastRow || $matches[1] !== $matches[4]) {
                 return ExcelError::VALUE();
             }
             $referenceCellCoordinate = $matches[1] . $ourRow;

src/PhpSpreadsheet/Reader/Xml.php

@@ -403,11 +403,16 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet, boo
 
                     $columnID = 'A';
                     foreach ($rowData->Cell as $cell) {
+                        $arrayRef = '';
                         $cell_ss = self::getAttributes($cell, self::NAMESPACES_SS);
                         if (isset($cell_ss['Index'])) {
                             $columnID = Coordinate::stringFromColumnIndex((int) $cell_ss['Index']);
                         }
                         $cellRange = $columnID . $rowID;
+                        if (isset($cell_ss['ArrayRange'])) {
+                            $arrayRange = (string) $cell_ss['ArrayRange'];
+                            $arrayRef = AddressHelper::convertFormulaToA1($arrayRange, $rowID, Coordinate::columnIndexFromString($columnID));
+                        }
 
                         if ($this->getReadFilter() !== null) {
                             if (!$this->getReadFilter()->readCell($columnID, $rowID, $worksheetName)) {
@@ -440,6 +445,9 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet, boo
                         if (isset($cell_ss['Formula'])) {
                             $cellDataFormula = $cell_ss['Formula'];
                             $hasCalculatedValue = true;
+                            if ($arrayRef !== '') {
+                                $spreadsheet->getActiveSheet()->getCell($columnID . $rowID)->setFormulaAttributes(['t' => 'array', 'ref' => $arrayRef]);
+                            }
                         }
                         if (isset($cell->Data)) {
                             $cellData = $cell->Data;

src/PhpSpreadsheet/Worksheet/Worksheet.php

@@ -3695,4 +3695,24 @@ public function calculateArrays(bool $preCalculateFormulas = true): void
             }
         }
     }
+
+    public function isCellInSpillRange(string $coordinate): bool
+    {
+        if (Calculation::getArrayReturnType() !== Calculation::RETURN_ARRAY_AS_ARRAY) {
+            return false;
+        }
+        $this->calculateArrays();
+        $keys = $this->cellCollection->getCoordinates();
+        foreach ($keys as $key) {
+            $attributes = $this->getCell($key)->getFormulaAttributes();
+            if (isset($attributes['ref'])) {
+                if (Coordinate::coordinateIsInsideRange($attributes['ref'], $coordinate)) {
+                    // false for first cell in range, true otherwise
+                    return $coordinate !== $key;
+                }
+            }
+        }
+
+        return false;
+    }
 }

tests/PhpSpreadsheetTests/Calculation/InternalFunctionsTest.php

@@ -113,6 +113,10 @@ public static function singleDataProvider(): array
                 'G3:G5',
                 '#VALUE!',
             ],
+            'range which includes current row but spans columns' => [
+                'F7:G9',
+                '#VALUE!',
+            ],
         ];
     }
 }