Merge pull request #30 from box/allow_custom_sheet_name_xlsx_writer

Allow custom sheet name in the XLSX writer

README.md

@@ -180,6 +180,23 @@ It is also possible to retrieve all the sheets currently created:
 $sheets = $writer->getSheets();
 ```
 
+If you rely on the sheet's name in your application, you can access it and customize it this way:
+```php
+// Accessing the sheet name when reading
+while ($reader->hasNextSheet()) {
+    $sheet = $reader->nextSheet();
+    $sheetName = $sheet->getName();
+}
+
+// Accessing the sheet name when writing
+$sheet = $writer->getCurrentSheet();
+$sheetName = $sheet->getName();
+
+// Customizing the sheet name when writing
+$sheet = $writer->getCurrentSheet();
+$sheetName = $sheet->setName('My custom name');
+``` 
+
 ### Fluent interface
 
 Because fluent interfaces are great, you can use them with Spout:

src/Spout/Writer/Internal/XLSX/Worksheet.php

@@ -97,7 +97,7 @@ EOD;
     public function getId()
     {
         // sheet number is zero-based, while ID is 1-based
-        return $this->externalSheet->getSheetNumber() + 1;
+        return $this->externalSheet->getNumber() + 1;
     }
 
     /**

src/Spout/Writer/Sheet.php

@@ -30,7 +30,7 @@ class Sheet
     /**
      * @return int Number of the sheet, based on order of creation (zero-based)
      */
-    public function getSheetNumber()
+    public function getNumber()
     {
         return $this->sheetNumber;
     }
@@ -42,4 +42,14 @@ class Sheet
     {
         return $this->name;
     }
+
+    /**
+     * @param string $name Name of the sheet
+     * @return \Box\Spout\Writer\Sheet
+     */
+    public function setName($name)
+    {
+        $this->name = $name;
+        return $this;
+    }
 }

tests/Spout/Writer/SheetTest.php

@@ -22,8 +22,8 @@ class SheetTest extends \PHPUnit_Framework_TestCase
         $sheets = $this->writeDataAndReturnSheets('test_get_sheet_number.xlsx');
 
         $this->assertEquals(2, count($sheets), '2 sheets should have been created');
-        $this->assertEquals(0, $sheets[0]->getSheetNumber(), 'The first sheet should be number 0');
+        $this->assertEquals(0, $sheets[0]->getNumber(), 'The first sheet should be number 0');
-        $this->assertEquals(1, $sheets[1]->getSheetNumber(), 'The second sheet should be number 1');
+        $this->assertEquals(1, $sheets[1]->getNumber(), 'The second sheet should be number 1');
     }
 
     /**

tests/Spout/Writer/XLSXTest.php

@@ -343,6 +343,27 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         $this->assertInlineDataWasWrittenToSheet($fileName, 1, 'control's _x0015_ "character"');
     }
 
+    /**
+     * @return void
+     */
+    public function testSetNameShouldCreateSheetWithCustomName()
+    {
+        $fileName = 'test_set_name_should_create_sheet_with_custom_name.xlsx';
+        $this->createGeneratedFolderIfNeeded($fileName);
+        $resourcePath = $this->getGeneratedResourcePath($fileName);
+
+        $writer = WriterFactory::create(Type::XLSX);
+        $writer->openToFile($resourcePath);
+
+        $customSheetName = 'CustomName';
+        $sheet = $writer->getCurrentSheet();
+        $sheet->setName($customSheetName);
+
+        $writer->addRow(['xlsx--11', 'xlsx--12']);
+        $writer->close();
+
+        $this->assertSheetNameEquals($customSheetName, $resourcePath, "The sheet name should have been changed to '$customSheetName'");
+    }
 
     /**
      * @param array $allRows
@@ -445,4 +466,18 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
 
         $this->assertContains($sharedString, $xmlContents, $message);
     }
+
+    /**
+     * @param string $expectedName
+     * @param string $resourcePath
+     * @param string $message
+     * @return void
+     */
+    private function assertSheetNameEquals($expectedName, $resourcePath, $message = '')
+    {
+        $pathToWorkbookFile = $resourcePath . '#xl/workbook.xml';
+        $xmlContents = file_get_contents('zip://' . $pathToWorkbookFile);
+
+        $this->assertContains('<sheet name="' . $expectedName . '"', $xmlContents, $message);
+    }
 }