Merge pull request #3256 from PHPOffice/Reader-Writer-Flags

Reader/Writer flags

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
+- Extended flag options for the Reader `load()` and Writer `save()` methods
 - Apply Row/Column limits (1048576 and XFD) in ReferenceHelper [PR #3213](https://github.com/PHPOffice/PhpSpreadsheet/pull/3213)
 - Allow the creation of In-Memory Drawings from a string of binary image data, or from a stream. [PR #3157](https://github.com/PHPOffice/PhpSpreadsheet/pull/3157)
 - Xlsx Reader support for Pivot Tables [PR #2829](https://github.com/PHPOffice/PhpSpreadsheet/pull/2829)

docs/topics/reading-and-writing-to-file.md

@@ -861,11 +861,11 @@ of different libraries.
 
 Currently, the following libraries are supported:
 
-Library | Downloadable from                   | PhpSpreadsheet writer
---------|-------------------------------------|----------------------
-TCPDF   | https://github.com/tecnickcom/tcpdf | Tcpdf
-mPDF    | https://github.com/mpdf/mpdf        | Mpdf
-Dompdf  | https://github.com/dompdf/dompdf    | Dompdf
+| Library | Downloadable from                   | PhpSpreadsheet writer |
+|---------|-------------------------------------|-----------------------|
+| TCPDF   | https://github.com/tecnickcom/tcpdf | Tcpdf                 |
+| mPDF    | https://github.com/mpdf/mpdf        | Mpdf                  |
+| Dompdf  | https://github.com/dompdf/dompdf    | Dompdf                |
 
 The different libraries have different strengths and weaknesses. Some
 generate better formatted output than others, some are faster or use
@@ -1083,6 +1083,22 @@ If you wish to use the IOFactory `load()` method rather than instantiating a spe
 $spreadsheet = \PhpOffice\PhpSpreadsheet\IOFactory::load("spreadsheetWithCharts.xlsx", \PhpOffice\PhpSpreadsheet\Reader\IReader::LOAD_WITH_CHARTS);
 ```
 
+Flags that are available that can be passed to the Reader in this way include:
+ - $reader::LOAD_WITH_CHARTS
+ - $reader::READ_DATA_ONLY
+ - $reader::SKIP_EMPTY_CELLS
+
+| Readers  | LOAD_WITH_CHARTS | READ_DATA_ONLY | SKIP_EMPTY_CELLS |
+|----------|------------------|----------------|------------------|
+| Xlsx     | YES              | YES            | YES              |
+| Xls      | NO               | YES            | YES              |
+| Xml      | NO               | NO             | NO               |
+| Ods      | NO               | YES            | NO               |
+| Gnumeric | NO               | YES            | NO               |
+| Html     | N/A              | N/A            | N/A              |
+| Slk      | N/A              | NO             | NO               |
+| Csv      | N/A              | NO             | NO               |
+
 Likewise, when saving a file using a Writer, loaded charts wil not be saved unless you explicitly tell the Writer to include them:
 
 ```php
@@ -1097,26 +1113,25 @@ $writer = IOFactory::createWriter($spreadsheet, 'Xlsx');
 $writer->save('mySavedFileWithCharts.xlsx', \PhpOffice\PhpSpreadsheet\Writer\IWriter::SAVE_WITH_CHARTS);
 ```
 
-Currently, the only special "Feature Flag" that is supported in this way is the inclusion of Charts, and only for certain formats.
+Flags that are available that can be passed to the Reader in this way include:
+- $reader::SAVE_WITH_CHARTS
+- $reader::DISABLE_PRECALCULATE_FORMULAE
 
-Readers  | LOAD_WITH_CHARTS |
----------|------------------|
-Xlsx     |       YES        |
-Xls      |       NO         |
-Xml      |       NO         |
-Ods      |       NO         |
-Gnumeric |       NO         |
-Html     |       N/A        |
-Slk      |       N/A        |
-Csv      |       N/A        |
+| Writers | SAVE_WITH_CHARTS | DISABLE_PRECALCULATE_FORMULAE |
+|---------|------------------|-------------------------------|
+| Xlsx    | YES              | YES                           |
+| Xls     | NO               | NO                            |
+| Ods     | NO               | YES                           |
+| Html    | YES              | YES                           |
+| Pdf     | YES              | YES                           |
+| Csv     | N/A              | YES                           |
 
+### Combining Flags
 
-Writers | SAVE_WITH_CHARTS |
---------|------------------|
-Xlsx    |        YES       |
-Xls     |        NO        |
-Ods     |        NO        |
-Html    |        YES       |
-Pdf     |        YES       |
-Csv     |        N/A       |
+One benefit of flags is that you can pass several flags in a single method call.
+Two or more flags can be passed together using PHP's `|` operator.
 
+```php
+$reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReaderForFile("myExampleFile.xlsx");
+$reader->load("spreadsheetWithCharts.xlsx", $reader::READ_DATA_ONLY | $reader::SKIP_EMPTY_CELLS);
+```

src/PhpSpreadsheet/Reader/BaseReader.php

@@ -144,6 +144,12 @@ protected function processFlags(int $flags): void
         if (((bool) ($flags & self::LOAD_WITH_CHARTS)) === true) {
             $this->setIncludeCharts(true);
         }
+        if (((bool) ($flags & self::READ_DATA_ONLY)) === true) {
+            $this->setReadDataOnly(true);
+        }
+        if (((bool) ($flags & self::SKIP_EMPTY_CELLS)) === true) {
+            $this->setReadEmptyCells(false);
+        }
     }
 
     protected function loadSpreadsheetFromFile(string $filename): Spreadsheet

src/PhpSpreadsheet/Reader/IReader.php

@@ -6,6 +6,10 @@ interface IReader
 {
     public const LOAD_WITH_CHARTS = 1;
 
+    public const READ_DATA_ONLY = 2;
+
+    public const SKIP_EMPTY_CELLS = 4;
+
     /**
      * IReader constructor.
      */
@@ -123,6 +127,13 @@ public function setReadFilter(IReadFilter $readFilter);
     /**
      * Loads PhpSpreadsheet from file.
      *
+     * @param string $filename The name of the file to load
+     * @param int $flags Flags that can change the behaviour of the Writer:
+     *            self::LOAD_WITH_CHARTS    Load any charts that are defined (if the Reader supports Charts)
+     *            self::READ_DATA_ONLY      Read only data, not style or structure information, from the file
+     *            self::SKIP_EMPTY_CELLS    Don't read empty cells (cells that contain a null value,
+     *                                      empty string, or a string containing only whitespace characters)
+     *
      * @return \PhpOffice\PhpSpreadsheet\Spreadsheet
      */
     public function load(string $filename, int $flags = 0);

src/PhpSpreadsheet/Writer/BaseWriter.php

@@ -99,6 +99,9 @@ protected function processFlags(int $flags): void
         if (((bool) ($flags & self::SAVE_WITH_CHARTS)) === true) {
             $this->setIncludeCharts(true);
         }
+        if (((bool) ($flags & self::DISABLE_PRECALCULATE_FORMULAE)) === true) {
+            $this->setPreCalculateFormulas(false);
+        }
     }
 
     /**

src/PhpSpreadsheet/Writer/IWriter.php

@@ -8,6 +8,8 @@ interface IWriter
 {
     public const SAVE_WITH_CHARTS = 1;
 
+    public const DISABLE_PRECALCULATE_FORMULAE = 2;
+
     /**
      * IWriter constructor.
      *
@@ -62,6 +64,9 @@ public function setPreCalculateFormulas($precalculateFormulas);
      * Save PhpSpreadsheet to file.
      *
      * @param resource|string $filename Name of the file to save
+     * @param int $flags Flags that can change the behaviour of the Writer:
+     *            self::SAVE_WITH_CHARTS                Save any charts that are defined (if the Writer supports Charts)
+     *            self::DISABLE_PRECALCULATE_FORMULAE   Don't Precalculate formulae before saving the file
      *
      * @throws Exception
      */