Add Spreadsheet Method for Duplicating Worksheet

Cloning a worksheet attached to a spreadsheet creates a clone which is detached from the spreadsheet. This can have its uses, but I think it would also be useful to have the ability to duplicate the worksheet and keep the duplicate attached to the spreadsheet. You can do that in Excel and LibreOffice, and you can now do it in PhpSpreadsheet as well. The duplicated worksheet will come immediately after its source.

The worksheet being duplicated could be identified in a number of ways - by passing the worksheet itself to the new method, by passing the worksheet title, or by passing the index of the worksheet within the spreadsheet. For now, I am just implementing the one I think is most useful (title).

docs/topics/worksheets.md

@@ -95,19 +95,38 @@ insert the clone into the workbook.
 
 ```php
 $clonedWorksheet = clone $spreadsheet->getSheetByName('Worksheet 1');
-$clonedWorksheet->setTitle('Copy of Worksheet 1');
+$clonedWorksheet->setTitle('Copy of Worksheet 1'); // must be unique
 $spreadsheet->addSheet($clonedWorksheet);
 ```
+Starting with PhpSpreadsheet 3.9.0, this can be done more simply (copied sheet's title will be set to something unique):
+```php
+$copiedWorksheet = $spreadsheet->duplicateWorksheetByTitle('sheetname');
+```
 
 You can also copy worksheets from one workbook to another, though this
 is more complex as PhpSpreadsheet also has to replicate the styling
 between the two workbooks. The `addExternalSheet()` method is provided for
 this purpose.
 
-    $clonedWorksheet = clone $spreadsheet1->getSheetByName('Worksheet 1');
-    $spreadsheet->addExternalSheet($clonedWorksheet);
+```php
+$clonedWorksheet = clone $spreadsheet1->getSheetByName('Worksheet 1');
+$clonedWorksheet->setTitle('Copy of Worksheet 1'); // must be unique
+$spreadsheet1->addSheet($clonedWorksheet);
+$spreadsheet->addExternalSheet($clonedWorksheet);
+```
+Starting with PhpSpreadsheet 3.8.0, this can be simplified:
+```php
+$clonedWorksheet = clone $spreadsheet1->getSheetByName('Worksheet 1');
+$spreadsheet1->addSheet($clonedWorksheet, null, true);
+$spreadsheet->addExternalSheet($clonedWorksheet);
+```
+Starting with PhpSpreadsheet 3.9.0, this can be simplified even further:
+```php
+$clonedWorksheet = $spreadsheet1->duplicateWorksheetByTitle('sheetname');
+$spreadsheet->addExternalSheet($clonedWorksheet);
+```
 
-In both cases, it is the developer's responsibility to ensure that
+In the cases commented "must be unique", it is the developer's responsibility to ensure that
 worksheet names are not duplicated. PhpSpreadsheet will throw an
 exception if you attempt to copy worksheets that will result in a
 duplicate name.

src/PhpSpreadsheet/Spreadsheet.php

@@ -529,6 +529,15 @@ public function sheetNameExists(string $worksheetName): bool
         return $this->getSheetByName($worksheetName) !== null;
     }
 
+    public function duplicateWorksheetByTitle(string $title): Worksheet
+    {
+        $original = $this->getSheetByNameOrThrow($title);
+        $index = $this->getIndex($original) + 1;
+        $clone = clone $original;
+
+        return $this->addSheet($clone, $index, true);
+    }
+
     /**
      * Add sheet.
      *

tests/PhpSpreadsheetTests/SpreadsheetDuplicateSheetTest.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpOffice\PhpSpreadsheetTests;
+
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PHPUnit\Framework\TestCase;
+
+class SpreadsheetDuplicateSheetTest extends TestCase
+{
+    private ?Spreadsheet $spreadsheet = null;
+
+    protected function tearDown(): void
+    {
+        if ($this->spreadsheet !== null) {
+            $this->spreadsheet->disconnectWorksheets();
+            $this->spreadsheet = null;
+        }
+    }
+
+    public function testDuplicate(): void
+    {
+        $this->spreadsheet = new Spreadsheet();
+        $sheet = $this->spreadsheet->getActiveSheet();
+        $sheet->setTitle('original');
+        $sheet->getCell('A1')->setValue('text1');
+        $sheet->getCell('A2')->setValue('text2');
+        $sheet->getStyle('A1')
+            ->getFont()
+            ->setBold(true);
+        $sheet3 = $this->spreadsheet->createSheet();
+        $sheet3->setTitle('added');
+        $newSheet = $this->spreadsheet
+            ->duplicateWorksheetByTitle('original');
+        $this->spreadsheet->duplicateWorksheetByTitle('added');
+        self::assertSame('original 1', $newSheet->getTitle());
+        self::assertSame(
+            'text1',
+            $newSheet->getCell('A1')->getValue()
+        );
+        self::assertSame(
+            'text2',
+            $newSheet->getCell('A2')->getValue()
+        );
+        self::assertTrue(
+            $newSheet->getStyle('A1')->getFont()->getBold()
+        );
+        self::assertFalse(
+            $newSheet->getStyle('A2')->getFont()->getBold()
+        );
+        $sheetNames = [];
+        foreach ($this->spreadsheet->getWorksheetIterator() as $worksheet) {
+            $sheetNames[] = $worksheet->getTitle();
+        }
+        $expected = ['original', 'original 1', 'added', 'added 1'];
+        self::assertSame($expected, $sheetNames);
+    }
+}