Merge pull request #3066 from PHPOffice/Issue-3065_Merge-Cell-Options

Additional options for mergeCells() method

Author: MarkBaker

CHANGELOG.md

@@ -17,7 +17,11 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Changed
 
-- Nothing
+- Allow variant behaviour when merging cells [Issue #3065](https://github.com/PHPOffice/PhpSpreadsheet/issues/3065)
+  - Merge methods now allow an additional `$behaviour` argument. Permitted values are:
+    - Worksheet::MERGE_CELL_CONTENT_EMPTY - Empty the content of the hidden cells (the default behaviour)
+    - Worksheet::MERGE_CELL_CONTENT_HIDE - Keep the content of the hidden cells
+    - Worksheet::MERGE_CELL_CONTENT_MERGE - Move the content of the hidden cells into the first cell
 
 ### Deprecated
 

docs/topics/images/12-01-MergeCells-Options-2.png

@@ -1332,22 +1332,72 @@ rows (default), or above. The following code adds the summary above:
 $spreadsheet->getActiveSheet()->setShowSummaryBelow(false);
 ```
 
-## Merge/unmerge cells
+## Merge/Unmerge cells
 
-If you have a big piece of data you want to display in a worksheet, you
-can merge two or more cells together, to become one cell. This can be
-done using the following code:
+If you have a big piece of data you want to display in a worksheet, or a
+heading that needs to span multiple sub-heading columns, you can merge
+two or more cells together, to become one cell. This can be done using
+the following code:
 
 ```php
 $spreadsheet->getActiveSheet()->mergeCells('A18:E22');
 ```
 
-Removing a merge can be done using the unmergeCells method:
+Removing a merge can be done using the `unmergeCells()` method:
 
 ```php
 $spreadsheet->getActiveSheet()->unmergeCells('A18:E22');
 ```
 
+MS Excel itself doesn't yet offer the functionality to simply hide the merged cells, or to merge the content of cells into a single cell, but it is available in Open/Libre Office.
+
+### Merge with MERGE_CELL_CONTENT_EMPTY
+
+The default behaviour is to empty all cells except for the top-left corner cell in the merge range; and this is also the default behaviour for the `mergeCells()` method in PhpSpreadsheet.
+When this behaviour is applied, those cell values will be set to null; and if they are subsequently Unmerged, they will be empty cells.
+
+Passing an extra flag value to the `mergeCells()` method in PhpSpreadsheet can change this behaviour.
+
+![12-01-MergeCells-Options.png](./images/12-01-MergeCells-Options.png)
+
+Possible flag values are:
+- Worksheet::MERGE_CELL_CONTENT_EMPTY (the default)
+- Worksheet::MERGE_CELL_CONTENT_HIDE
+- Worksheet::MERGE_CELL_CONTENT_MERGE
+
+### Merge with MERGE_CELL_CONTENT_HIDE
+
+The first alternative, available only in OpenOffice, is to hide those cells, but to leave their content intact.
+When a file saved as `Xlsx` in those applications is opened in MS Excel, and those cells are unmerged, the original content will still be present.
+
+```php
+$spreadsheet->getActiveSheet()->mergeCells('A1:C3', Worksheet::MERGE_CELL_CONTENT_HIDE);
+```
+
+Will replicate that behaviour.
+
+### Merge with MERGE_CELL_CONTENT_MERGE
+
+The second alternative, available in both OpenOffice and LibreOffice is to merge the content of every cell in the merge range into the top-left cell, while setting those hidden cells to empty.
+
+```php
+$spreadsheet->getActiveSheet()->mergeCells('A1:C3', Worksheet::MERGE_CELL_CONTENT_MERGE);
+```
+
+Particularly when the merged cells contain formulae, the logic for this merge seems strange:
+walking through the merge range, each cell is calculated in turn, and appended to the "master" cell, then it is emptied, so any subsequent calculations that reference the cell see an empty cell, not the pre-merge value. 
+For example, suppose our spreadsheet contains
+
+![12-01-MergeCells-Options-2.png](./images/12-01-MergeCells-Options-2.png)
+
+where `B2` is the formula `=5-B1` and `C2` is the formula `=A2/B2`,
+and we want to merge cells `A2` to `C2` with all the cell values merged.
+The result is:
+
+![12-01-MergeCells-Options-3.png](./images/12-01-MergeCells-Options-3.png)
+
+The cell value `12` from cell `A2` is fixed; the value from `B2` is the result of the formula `=5-B1` (`4`, which is appended to our merged value), and cell `B2` is then emptied, so when we evaluate cell `C2` with the formula `=A2/B2` it gives us `12 / 0` which results in a `#DIV/0!` error (so the error `#DIV/0!` is appended to our merged value rather than the original calculation result of `3`).
+
 ## Inserting or Removing rows/columns
 
 You can insert/remove rows/columns at a specific position. The following

docs/topics/images/12-01-MergeCells-Options-3.png

@@ -363,7 +363,7 @@ private function processMergedCells(?SimpleXMLElement $sheet): void
         if ($sheet !== null && isset($sheet->MergedRegions)) {
             foreach ($sheet->MergedRegions->Merge as $mergeCells) {
                 if (strpos((string) $mergeCells, ':') !== false) {
-                    $this->spreadsheet->getActiveSheet()->mergeCells($mergeCells);
+                    $this->spreadsheet->getActiveSheet()->mergeCells($mergeCells, Worksheet::MERGE_CELL_CONTENT_HIDE);
                 }
             }
         }

docs/topics/images/12-01-MergeCells-Options.png

@@ -20,6 +20,7 @@
 use PhpOffice\PhpSpreadsheet\Shared\File;
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat;
+use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;
 use Throwable;
 use XMLReader;
 use ZipArchive;
@@ -759,7 +760,7 @@ private function processMergedCells(
                 }
 
                 $cellRange = $columnID . $rowID . ':' . $columnTo . $rowTo;
-                $spreadsheet->getActiveSheet()->mergeCells($cellRange);
+                $spreadsheet->getActiveSheet()->mergeCells($cellRange, Worksheet::MERGE_CELL_CONTENT_HIDE);
             }
         }
     }

docs/topics/recipes.md

@@ -4585,7 +4585,7 @@ private function readMergedCells(): void
                     (strpos($cellRangeAddress, ':') !== false) &&
                     ($this->includeCellRangeFiltered($cellRangeAddress))
                 ) {
-                    $this->phpSheet->mergeCells($cellRangeAddress);
+                    $this->phpSheet->mergeCells($cellRangeAddress, Worksheet::MERGE_CELL_CONTENT_HIDE);
                 }
             }
         }

src/PhpSpreadsheet/Reader/Gnumeric.php

@@ -914,7 +914,7 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet
                                 foreach ($xmlSheet->mergeCells->mergeCell as $mergeCell) {
                                     $mergeRef = (string) $mergeCell['ref'];
                                     if (strpos($mergeRef, ':') !== false) {
-                                        $docSheet->mergeCells((string) $mergeCell['ref']);
+                                        $docSheet->mergeCells((string) $mergeCell['ref'], Worksheet::MERGE_CELL_CONTENT_HIDE);
                                     }
                                 }
                             }

src/PhpSpreadsheet/Reader/Ods.php

@@ -18,6 +18,7 @@
 use PhpOffice\PhpSpreadsheet\Shared\File;
 use PhpOffice\PhpSpreadsheet\Shared\StringHelper;
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;
 use SimpleXMLElement;
 
 /**
@@ -364,7 +365,7 @@ public function loadIntoExisting($filename, Spreadsheet $spreadsheet)
                                 $rowTo = $rowTo + $cell_ss['MergeDown'];
                             }
                             $cellRange .= ':' . $columnTo . $rowTo;
-                            $spreadsheet->getActiveSheet()->mergeCells($cellRange);
+                            $spreadsheet->getActiveSheet()->mergeCells($cellRange, Worksheet::MERGE_CELL_CONTENT_HIDE);
                         }
 
                         $hasCalculatedValue = false;