Add Spreadsheet Method for Duplicating Worksheet

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
-- Nothing yet.
+- Method for duplicating worksheet in spreadsheet. [PR #4315](https://github.com/PHPOffice/PhpSpreadsheet/pull/4315)
 
 ### Changed
 

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);
+    }
+}