Merge pull request #4618 from oleibman/blanksheet

oleibman · web-flow · commit ff7195c2741c · 2025-09-01T06:45:12.000Z
Option to Create Blank Sheet If LoadSheetsOnly Doesn't Find Any
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org). Thia is a
 - Add Conditional Formatting with IconSet (Xlsx only). [Issue #4560](https://github.com/PHPOffice/PhpSpreadsheet/issues/4560) [PR #4574](https://github.com/PHPOffice/PhpSpreadsheet/pull/4574)
 - Copy cell adjusting formula. [Issue #1203](https://github.com/PHPOffice/PhpSpreadsheet/issues/1203) [PR #4577](https://github.com/PHPOffice/PhpSpreadsheet/pull/4577)
 - splitRange and ProtectedRange. [Issue #1457](https://github.com/PHPOffice/PhpSpreadsheet/issues/1457) [PR #4580](https://github.com/PHPOffice/PhpSpreadsheet/pull/4580)
+- Option to create blank sheet if LoadSheetsOnly doesn't find any. [PR #4618](https://github.com/PHPOffice/PhpSpreadsheet/pull/4618)
 
 ### Removed
 
@@ -34,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org). Thia is a
 - Google-only formulas exported from Google Sheets. [Issue #1637](https://github.com/PHPOffice/PhpSpreadsheet/issues/1637) [PR #4579](https://github.com/PHPOffice/PhpSpreadsheet/pull/4579)
 - Maximum column width. [PR #4581](https://github.com/PHPOffice/PhpSpreadsheet/pull/4581)
 - PrintArea after row/column delete. [Issue #2912](https://github.com/PHPOffice/PhpSpreadsheet/issues/2912) [PR #4598](https://github.com/PHPOffice/PhpSpreadsheet/pull/4598)
+- Excel 2007 problem with newlines. [Issue #4619](https://github.com/PHPOffice/PhpSpreadsheet/issues/4619) [PR #4620](https://github.com/PHPOffice/PhpSpreadsheet/pull/4620)
 
 ## 2025-08-10 - 5.0.0
 
diff --git a/src/PhpSpreadsheet/Reader/BaseReader.php b/src/PhpSpreadsheet/Reader/BaseReader.php
@@ -54,6 +54,12 @@ abstract class BaseReader implements IReader
      */
     protected bool $allowExternalImages = false;
 
+    /**
+     * Create a blank sheet if none are read,
+     * possibly due to a typo when using LoadSheetsOnly.
+     */
+    protected bool $createBlankSheetIfNoneRead = false;
+
     /**
      * IReadFilter instance.
      */
@@ -173,6 +179,17 @@ public function getAllowExternalImages(): bool
         return $this->allowExternalImages;
     }
 
+    /**
+     * Create a blank sheet if none are read,
+     * possibly due to a typo when using LoadSheetsOnly.
+     */
+    public function setCreateBlankSheetIfNoneRead(bool $createBlankSheetIfNoneRead): self
+    {
+        $this->createBlankSheetIfNoneRead = $createBlankSheetIfNoneRead;
+
+        return $this;
+    }
+
     public function getSecurityScanner(): ?XmlScanner
     {
         return $this->securityScanner;
@@ -207,6 +224,9 @@ protected function processFlags(int $flags): void
         if (((bool) ($flags & self::DONT_ALLOW_EXTERNAL_IMAGES)) === true) {
             $this->setAllowExternalImages(false);
         }
+        if (((bool) ($flags & self::CREATE_BLANK_SHEET_IF_NONE_READ)) === true) {
+            $this->setCreateBlankSheetIfNoneRead(true);
+        }
     }
 
     protected function loadSpreadsheetFromFile(string $filename): Spreadsheet
diff --git a/src/PhpSpreadsheet/Reader/Gnumeric.php b/src/PhpSpreadsheet/Reader/Gnumeric.php
@@ -269,6 +269,7 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet): Sp
         (new Properties($this->spreadsheet))->readProperties($xml, $gnmXML);
 
         $worksheetID = 0;
+        $sheetCreated = false;
         foreach ($gnmXML->Sheets->Sheet as $sheetOrNull) {
             $sheet = self::testSimpleXml($sheetOrNull);
             $worksheetName = (string) $sheet->Name;
@@ -280,6 +281,7 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet): Sp
 
             // Create new Worksheet
             $this->spreadsheet->createSheet();
+            $sheetCreated = true;
             $this->spreadsheet->setActiveSheetIndex($worksheetID);
             //    Use false for $updateFormulaCellReferences to prevent adjustment of worksheet references in formula
             //        cells... during the load, all formulae should be correct, and we're simply bringing the worksheet
@@ -329,6 +331,9 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet): Sp
             $this->setSelectedCells($sheet);
             ++$worksheetID;
         }
+        if ($this->createBlankSheetIfNoneRead && !$sheetCreated) {
+            $this->spreadsheet->createSheet();
+        }
 
         $this->processDefinedNames($gnmXML);
 
diff --git a/src/PhpSpreadsheet/Reader/IReader.php b/src/PhpSpreadsheet/Reader/IReader.php
@@ -41,6 +41,8 @@ interface IReader
     public const ALLOW_EXTERNAL_IMAGES = 16;
     public const DONT_ALLOW_EXTERNAL_IMAGES = 32;
 
+    public const CREATE_BLANK_SHEET_IF_NONE_READ = 64;
+
     public function __construct();
 
     /**
@@ -149,6 +151,12 @@ public function setAllowExternalImages(bool $allowExternalImages): self;
 
     public function getAllowExternalImages(): bool;
 
+    /**
+     * Create a blank sheet if none are read,
+     * possibly due to a typo when using LoadSheetsOnly.
+     */
+    public function setCreateBlankSheetIfNoneRead(bool $createBlankSheetIfNoneRead): self;
+
     /**
      * Loads PhpSpreadsheet from file.
      *
@@ -161,6 +169,7 @@ public function getAllowExternalImages(): bool;
      *            self::IGNORE_ROWS_WITH_NO_CELLS    Don't load any rows that contain no cells.
      *            self::ALLOW_EXTERNAL_IMAGES    Attempt to fetch images stored outside the spreadsheet.
      *            self::DONT_ALLOW_EXTERNAL_IMAGES    Don't attempt to fetch images stored outside the spreadsheet.
+     *            self::CREATE_BLANK_SHEET_IF_NONE_READ    If no sheets are read, create a blank one.
      */
     public function load(string $filename, int $flags = 0): Spreadsheet;
 }
diff --git a/src/PhpSpreadsheet/Reader/Ods.php b/src/PhpSpreadsheet/Reader/Ods.php
@@ -318,6 +318,7 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet): Sp
             $tables = $workbookData->getElementsByTagNameNS($tableNs, 'table');
 
             $worksheetID = 0;
+            $sheetCreated = false;
             foreach ($tables as $worksheetDataSet) {
                 /** @var DOMElement $worksheetDataSet */
                 $worksheetName = $worksheetDataSet->getAttributeNS($tableNs, 'name');
@@ -335,6 +336,7 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet): Sp
 
                 // Create sheet
                 $spreadsheet->createSheet();
+                $sheetCreated = true;
                 $spreadsheet->setActiveSheetIndex($worksheetID);
 
                 if ($worksheetName || is_numeric($worksheetName)) {
@@ -441,6 +443,9 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet): Sp
                 );
                 ++$worksheetID;
             }
+            if ($this->createBlankSheetIfNoneRead && !$sheetCreated) {
+                $spreadsheet->createSheet();
+            }
 
             $autoFilterReader->read($workbookData);
             $definedNameReader->read($workbookData);
diff --git a/src/PhpSpreadsheet/Reader/Xls/LoadSpreadsheet.php b/src/PhpSpreadsheet/Reader/Xls/LoadSpreadsheet.php
@@ -153,6 +153,7 @@ protected function loadSpreadsheetFromFile2(string $filename, Xls $xls): Spreads
 
         // Parse the individual sheets
         $xls->activeSheetSet = false;
+        $sheetCreated = false;
         foreach ($xls->sheets as $sheet) {
             $selectedCells = '';
             if ($sheet['sheetType'] != 0x00) {
@@ -167,6 +168,7 @@ protected function loadSpreadsheetFromFile2(string $filename, Xls $xls): Spreads
 
             // add sheet to PhpSpreadsheet object
             $xls->phpSheet = $xls->spreadsheet->createSheet();
+            $sheetCreated = true;
             //    Use false for $updateFormulaCellReferences to prevent adjustment of worksheet references in formula
             //        cells... during the load, all formulae should be correct, and we're simply bringing the worksheet
             //        name in line with the formula, not the reverse
@@ -582,6 +584,9 @@ protected function loadSpreadsheetFromFile2(string $filename, Xls $xls): Spreads
                 $xls->phpSheet->setSelectedCells($selectedCells);
             }
         }
+        if ($xls->createBlankSheetIfNoneRead && !$sheetCreated) {
+            $xls->spreadsheet->createSheet();
+        }
         if ($xls->activeSheetSet === false) {
             $xls->spreadsheet->setActiveSheetIndex(0);
         }
diff --git a/src/PhpSpreadsheet/Reader/Xlsx.php b/src/PhpSpreadsheet/Reader/Xlsx.php
@@ -784,6 +784,7 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet
 
                     $charts = $chartDetails = [];
 
+                    $sheetCreated = false;
                     if ($xmlWorkbookNS->sheets) {
                         foreach ($xmlWorkbookNS->sheets->sheet as $eleSheet) {
                             $eleSheetAttr = self::getAttributes($eleSheet);
@@ -810,6 +811,7 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet
 
                             // Load sheet
                             $docSheet = $excel->createSheet();
+                            $sheetCreated = true;
                             //    Use false for $updateFormulaCellReferences to prevent adjustment of worksheet
                             //        references in formula cells... during the load, all formulae should be correct,
                             //        and we're simply bringing the worksheet name in line with the formula, not the
@@ -1897,6 +1899,9 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet
                             }
                         }
                     }
+                    if ($this->createBlankSheetIfNoneRead && !$sheetCreated) {
+                        $excel->createSheet();
+                    }
 
                     (new WorkbookView($excel))->viewSettings($xmlWorkbook, $mainNS, $mapSheetId, $this->readDataOnly);
 
diff --git a/src/PhpSpreadsheet/Reader/Xml.php b/src/PhpSpreadsheet/Reader/Xml.php
@@ -307,6 +307,7 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet, boo
         $worksheetID = 0;
         $xml_ss = $xml->children(self::NAMESPACES_SS);
 
+        $sheetCreated = false;
         /** @var null|SimpleXMLElement $worksheetx */
         foreach ($xml_ss->Worksheet as $worksheetx) {
             $worksheet = $worksheetx ?? new SimpleXMLElement('<xml></xml>');
@@ -321,6 +322,7 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet, boo
 
             // Create new Worksheet
             $spreadsheet->createSheet();
+            $sheetCreated = true;
             $spreadsheet->setActiveSheetIndex($worksheetID);
             $worksheetName = '';
             if (isset($worksheet_ss['Name'])) {
@@ -668,6 +670,9 @@ public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet, boo
             }
             ++$worksheetID;
         }
+        if ($this->createBlankSheetIfNoneRead && !$sheetCreated) {
+            $spreadsheet->createSheet();
+        }
 
         // Globally scoped defined names
         $activeSheetIndex = 0;
diff --git a/tests/PhpSpreadsheetTests/Functional/ReadBlankCellsTest.php b/tests/PhpSpreadsheetTests/Functional/ReadBlankCellsTest.php
@@ -48,6 +48,20 @@ public function testLoadDontReadEmptyCells(): void
         $reloadedSpreadsheet->disconnectWorksheets();
     }
 
+    /**
+     * Test load file ignoring empty cells.
+     */
+    public function testLoadDontReadEmptyCellsFlag(): void
+    {
+        $filename = 'tests/data/Reader/XLSX/blankcell.xlsx';
+        $reader = new Xlsx();
+        $reloadedSpreadsheet = $reader->load($filename, Xlsx::IGNORE_EMPTY_CELLS);
+        self::assertFalse($reloadedSpreadsheet->getActiveSheet()->getCellCollection()->has('B2'));
+        self::assertFalse($reloadedSpreadsheet->getActiveSheet()->getCellCollection()->has('C2'));
+        self::assertTrue($reloadedSpreadsheet->getActiveSheet()->getCellCollection()->has('C3'));
+        $reloadedSpreadsheet->disconnectWorksheets();
+    }
+
     /**
      * Test generate file with some empty cells.
      */
diff --git a/tests/PhpSpreadsheetTests/Reader/CreateBlankSheetIfNoneReadTest.php b/tests/PhpSpreadsheetTests/Reader/CreateBlankSheetIfNoneReadTest.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpOffice\PhpSpreadsheetTests\Reader;
+
+use PhpOffice\PhpSpreadsheet\Exception as SpreadsheetException;
+use PhpOffice\PhpSpreadsheet\IOFactory;
+use PhpOffice\PhpSpreadsheet\Reader;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+class CreateBlankSheetIfNoneReadTest extends TestCase
+{
+    #[DataProvider('providerIdentify')]
+    public function testExceptionIfNoSheet(string $file, string $expectedName, string $expectedClass): void
+    {
+        $this->expectException(SpreadsheetException::class);
+        $this->expectExceptionMessage('out of bounds index: 0');
+        $actual = IOFactory::identify($file);
+        self::assertSame($expectedName, $actual);
+        $reader = IOFactory::createReaderForFile($file);
+        self::assertSame($expectedClass, $reader::class);
+        $sheetlist = ['Unknown sheetname'];
+        $reader->setLoadSheetsOnly($sheetlist);
+        $reader->load($file);
+    }
+
+    #[DataProvider('providerIdentify')]
+    public function testCreateSheetIfNoSheet(string $file, string $expectedName, string $expectedClass): void
+    {
+        $actual = IOFactory::identify($file);
+        self::assertSame($expectedName, $actual);
+        $reader = IOFactory::createReaderForFile($file);
+        self::assertSame($expectedClass, $reader::class);
+        $reader->setCreateBlankSheetIfNoneRead(true);
+        $sheetlist = ['Unknown sheetname'];
+        $reader->setLoadSheetsOnly($sheetlist);
+        $spreadsheet = $reader->load($file);
+        $sheet = $spreadsheet->getActiveSheet();
+        self::assertSame('Worksheet', $sheet->getTitle());
+        self::assertCount(1, $spreadsheet->getAllSheets());
+        $spreadsheet->disconnectWorksheets();
+    }
+
+    public static function providerIdentify(): array
+    {
+        return [
+            ['samples/templates/26template.xlsx', 'Xlsx', Reader\Xlsx::class],
+            ['samples/templates/GnumericTest.gnumeric', 'Gnumeric', Reader\Gnumeric::class],
+            ['samples/templates/30template.xls', 'Xls', Reader\Xls::class],
+            ['samples/templates/OOCalcTest.ods', 'Ods', Reader\Ods::class],
+            ['samples/templates/excel2003.xml', 'Xml', Reader\Xml::class],
+        ];
+    }
+
+    public function testUsingFlage(): void
+    {
+        $file = 'samples/templates/26template.xlsx';
+        $reader = IOFactory::createReaderForFile($file);
+        $sheetlist = ['Unknown sheetname'];
+        $reader->setLoadSheetsOnly($sheetlist);
+        $spreadsheet = $reader->load($file, Reader\BaseReader::CREATE_BLANK_SHEET_IF_NONE_READ);
+        $sheet = $spreadsheet->getActiveSheet();
+        self::assertSame('Worksheet', $sheet->getTitle());
+        self::assertCount(1, $spreadsheet->getAllSheets());
+        $spreadsheet->disconnectWorksheets();
+    }
+}
diff --git a/tests/PhpSpreadsheetTests/Reader/Csv/BinderTest.php b/tests/PhpSpreadsheetTests/Reader/Csv/BinderTest.php
@@ -34,6 +34,7 @@ public function testLoadFromString(): void
 
         $reader2 = new Csv();
         $reader2->setValueBinder(new StringValueBinder());
+        self::assertInstanceOf(StringValueBinder::class, $reader2->getValueBinder());
         $spreadsheet2 = $reader2->loadSpreadsheetFromString($data);
         $sheet2 = $spreadsheet2->getActiveSheet();
         $sheet2->getCell('A3')->setValueExplicit(7, DataType::TYPE_STRING);
diff --git a/tests/PhpSpreadsheetTests/Reader/Xlsx/URLImageTest.php b/tests/PhpSpreadsheetTests/Reader/Xlsx/URLImageTest.php
@@ -45,12 +45,38 @@ public function testURLImageSourceAllowed(): void
         $spreadsheet->disconnectWorksheets();
     }
 
+    public function testURLImageSourceAllowedFlag(): void
+    {
+        if (getenv('SKIP_URL_IMAGE_TEST') === '1') {
+            self::markTestSkipped('Skipped due to setting of environment variable');
+        }
+        $filename = realpath(__DIR__ . '/../../../data/Reader/XLSX/urlImage.xlsx');
+        self::assertNotFalse($filename);
+        $reader = IOFactory::createReader('Xlsx');
+        $spreadsheet = $reader->load($filename, XlsxReader::ALLOW_EXTERNAL_IMAGES);
+        $worksheet = $spreadsheet->getActiveSheet();
+        $collection = $worksheet->getDrawingCollection();
+        self::assertCount(1, $collection);
+
+        foreach ($collection as $drawing) {
+            self::assertInstanceOf(Drawing::class, $drawing);
+            // Check if the source is a URL or a file path
+            self::assertTrue($drawing->getIsURL());
+            self::assertSame('https://phpspreadsheet.readthedocs.io/en/latest/topics/images/01-03-filter-icon-1.png', $drawing->getPath());
+            self::assertSame(IMAGETYPE_PNG, $drawing->getType());
+            self::assertSame(84, $drawing->getWidth());
+            self::assertSame(44, $drawing->getHeight());
+        }
+        $spreadsheet->disconnectWorksheets();
+    }
+
     public function testURLImageSourceNotAllowed(): void
     {
         $filename = realpath(__DIR__ . '/../../../data/Reader/XLSX/urlImage.xlsx');
         self::assertNotFalse($filename);
         $reader = IOFactory::createReader('Xlsx');
         $reader->setAllowExternalImages(false);
+        self::assertFalse($reader->getAllowExternalImages());
         $spreadsheet = $reader->load($filename);
         $worksheet = $spreadsheet->getActiveSheet();
         $collection = $worksheet->getDrawingCollection();
@@ -87,6 +113,18 @@ public function testURLImageSourceNotFoundNotAllowed(): void
         $spreadsheet->disconnectWorksheets();
     }
 
+    public function testURLImageSourceNotFoundNotAllowedFlag(): void
+    {
+        $filename = realpath(__DIR__ . '/../../../data/Reader/XLSX/urlImage.notfound.xlsx');
+        self::assertNotFalse($filename);
+        $reader = IOFactory::createReader('Xlsx');
+        $spreadsheet = $reader->load($filename, XlsxReader::DONT_ALLOW_EXTERNAL_IMAGES);
+        $worksheet = $spreadsheet->getActiveSheet();
+        $collection = $worksheet->getDrawingCollection();
+        self::assertCount(0, $collection);
+        $spreadsheet->disconnectWorksheets();
+    }
+
     public function testURLImageSourceBadProtocol(): void
     {
         $filename = realpath(__DIR__ . '/../../../data/Reader/XLSX/urlImage.bad.dontuse');

Original file line number	Diff line number	Diff line change
`@@ -784,6 +784,7 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet`
`784`	`784`
`785`	`785`	`$charts = $chartDetails = [];`
`786`	`786`
	`787`	`+ $sheetCreated = false;`
`787`	`788`	`if ($xmlWorkbookNS->sheets) {`
`788`	`789`	`foreach ($xmlWorkbookNS->sheets->sheet as $eleSheet) {`
`789`	`790`	`$eleSheetAttr = self::getAttributes($eleSheet);`
`@@ -810,6 +811,7 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet`
`810`	`811`
`811`	`812`	`// Load sheet`
`812`	`813`	`$docSheet = $excel->createSheet();`
	`814`	`+ $sheetCreated = true;`
`813`	`815`	`// Use false for $updateFormulaCellReferences to prevent adjustment of worksheet`
`814`	`816`	`// references in formula cells... during the load, all formulae should be correct,`
`815`	`817`	`// and we're simply bringing the worksheet name in line with the formula, not the`
`@@ -1897,6 +1899,9 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet`
`1897`	`1899`	`}`
`1898`	`1900`	`}`
`1899`	`1901`	`}`
	`1902`	`+ if ($this->createBlankSheetIfNoneRead && !$sheetCreated) {`
	`1903`	`+ $excel->createSheet();`
	`1904`	`+ }`
`1900`	`1905`
`1901`	`1906`	`(new WorkbookView($excel))->viewSettings($xmlWorkbook, $mainNS, $mapSheetId, $this->readDataOnly);`
`1902`	`1907`