Merge pull request #4163 from homersimpsons/chore/deprecate-skip-empty-cells

🗑️ Deprecate `IReader::SKIP_EMPTY_CELLS`

Author: oleibman

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

@@ -1113,19 +1113,19 @@ Flags that are available that can be passed to the Reader in this way include:
 
  - $reader::LOAD_WITH_CHARTS
  - $reader::READ_DATA_ONLY
- - $reader::IGNORE_EMPTY_CELLS 
- - $reader::SKIP_EMPTY_CELLS (synonym for IGNORE_EMPTY_CELLS)
-
-| Readers  | LOAD_WITH_CHARTS | READ_DATA_ONLY | IGNORE_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                 |
+ - $reader::IGNORE_EMPTY_CELLS
+ - $reader::IGNORE_ROWS_WITH_NO_CELLS
+
+| Readers  | LOAD_WITH_CHARTS | READ_DATA_ONLY | IGNORE_EMPTY_CELLS | IGNORE_ROWS_WITH_NO_CELLS |
+|----------|------------------|----------------|--------------------|---------------------------|
+| Xlsx     | YES              | YES            | YES                | YES                       |
+| Xls      | NO               | YES            | YES                | NO                        |
+| Xml      | NO               | NO             | NO                 | NO                        |
+| Ods      | NO               | YES            | NO                 | NO                        |
+| Gnumeric | NO               | YES            | NO                 | NO                        |
+| Html     | N/A              | N/A            | N/A                | N/A                       |
+| Slk      | N/A              | NO             | NO                 | NO                        |
+| Csv      | N/A              | NO             | NO                 | NO                        |
 
 Likewise, when saving a file using a Writer, loaded charts will not be saved unless you explicitly tell the Writer to include them:
 
@@ -1162,5 +1162,5 @@ 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);
+$reader->load("spreadsheetWithCharts.xlsx", $reader::READ_DATA_ONLY | $reader::IGNORE_EMPTY_CELLS);
 ```

src/PhpSpreadsheet/Reader/BaseReader.php

@@ -19,7 +19,7 @@ abstract class BaseReader implements IReader
 
     /**
      * Read empty cells?
-     * Identifies whether the Reader should read data values for cells all cells, or should ignore cells containing
+     * Identifies whether the Reader should read data values for all cells, or should ignore cells containing
      *         null value or empty string.
      */
     protected bool $readEmptyCells = true;
@@ -166,7 +166,7 @@ protected function processFlags(int $flags): void
         if (((bool) ($flags & self::READ_DATA_ONLY)) === true) {
             $this->setReadDataOnly(true);
         }
-        if (((bool) ($flags & self::SKIP_EMPTY_CELLS) || (bool) ($flags & self::IGNORE_EMPTY_CELLS)) === true) {
+        if (((bool) ($flags & self::IGNORE_EMPTY_CELLS)) === true) {
             $this->setReadEmptyCells(false);
         }
         if (((bool) ($flags & self::IGNORE_ROWS_WITH_NO_CELLS)) === true) {

src/PhpSpreadsheet/Reader/IReader.php

@@ -6,13 +6,36 @@
 
 interface IReader
 {
+    /**
+     * Flag used to load the charts.
+     *
+     * This flag is supported only for some formats.
+     */
     public const LOAD_WITH_CHARTS = 1;
 
+    /**
+     * Flag used to read data only, not style or structure information.
+     */
     public const READ_DATA_ONLY = 2;
 
-    public const SKIP_EMPTY_CELLS = 4;
+    /**
+     * @deprecated 3.4.0 use IGNORE_EMPTY_CELLS instead.
+     */
+    public const SKIP_EMPTY_CELLS = self::IGNORE_EMPTY_CELLS;
+
+    /**
+     * Flag used to ignore empty cells when reading.
+     *
+     * The ignored cells will not be instantiated.
+     */
     public const IGNORE_EMPTY_CELLS = 4;
 
+    /**
+     * Flag used to ignore rows without cells.
+     *
+     * This flag is supported only for some formats.
+     * This can heavily improve performance for some files.
+     */
     public const IGNORE_ROWS_WITH_NO_CELLS = 8;
 
     public function __construct();
@@ -119,7 +142,7 @@ public function setReadFilter(IReadFilter $readFilter): self;
      * @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,
+     *            self::IGNORE_EMPTY_CELLS  Don't read empty cells (cells that contain a null value,
      *                                      empty string, or a string containing only whitespace characters)
      */
     public function load(string $filename, int $flags = 0): Spreadsheet;