Merge branch 'master' into issue2768

Author: MarkBaker

.github/ISSUE_TEMPLATE.md

@@ -26,6 +26,20 @@ $spreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet();
 
 // add code that show the issue here...
 ```
+If this is an issue with reading a specific spreadsheet file, then it may be appropriate to provide a sample file that demonstrates the problem; but please keep it as small as possible, and sanitize any confidential information before uploading.
+
+### What features do you think are causing the issue
+
+- [ ] Reader
+- [ ] Writer
+- [ ] Styles
+- [ ] Data Validations
+- [ ] Formula Calulations
+- [ ] Charts
+- [ ] AutoFilter
+- [ ] Form Elements
+
+### Does an issue affect all spreadsheet file formats? If not, which formats are affected?
 
 
 ### Which versions of PhpSpreadsheet and PHP are affected?

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,14 +3,21 @@ This is:
 ```
 - [ ] a bugfix
 - [ ] a new feature
+- [ ] refactoring
+- [ ] additional unit tests
 ```
 
 Checklist:
 
 - [ ] Changes are covered by unit tests
+  - [ ] Changes are covered by existing unit tests
+  - [ ] New unit tests have been added
 - [ ] Code style is respected
 - [ ] Commit message explains **why** the change is made (see https://github.com/erlang/otp/wiki/Writing-good-commit-messages)
 - [ ] CHANGELOG.md contains a short summary of the change
 - [ ] Documentation is updated as necessary
 
 ### Why this change is needed?
+
+Provide an explanation of why this change is needed, with links to any Issues (if appropriate).
+If this is a bugfix or a new feature, and there are no existing Issues, then please also create an issue that will make it easier to track progress with this PR.

.php-cs-fixer.dist.php

@@ -21,7 +21,7 @@
         'braces' => true,
         'cast_spaces' => true,
         'class_attributes_separation' => ['elements' => ['method' => 'one', 'property' => 'one']], // const are often grouped with other related const
-        'class_definition' => true,
+        'class_definition' => false,
         'class_keyword_remove' => false, // ::class keyword gives us better support in IDE
         'combine_consecutive_issets' => true,
         'combine_consecutive_unsets' => true,

CHANGELOG.md

@@ -9,19 +9,29 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
-- Implementation of the FILTER(), SORT(), SORTBY() and UNIQUE() Lookup/Reference (array) functions
+- Ods Writer support for Freeze Pane [Issue #2013](https://github.com/PHPOffice/PhpSpreadsheet/issues/2013) [PR #2755](https://github.com/PHPOffice/PhpSpreadsheet/pull/2755)
+- Ods Writer support for setting column width/row height (including the use of AutoSize) [Issue #2346](https://github.com/PHPOffice/PhpSpreadsheet/issues/2346) [PR #2753](https://github.com/PHPOffice/PhpSpreadsheet/pull/2753)
+- Introduced CellAddress, CellRange, RowRange and ColumnRange value objects that can be used as an alternative to a string value (e.g. `'C5'`, `'B2:D4'`, `'2:2'` or `'B:C'`) in appropriate contexts.
+- Implementation of the FILTER(), SORT(), SORTBY() and UNIQUE() Lookup/Reference (array) functions.
 - Implementation of the ISREF() Information function.
 - Added support for reading "formatted" numeric values from Csv files; although default behaviour of reading these values as strings is preserved.
 
-  (i.e a value of "12,345.67" can be read as numeric `1235.67`, not simply as a string `"12,345.67"`, if the `castFormattedNumberToNumeric()` setting is enabled.
+  (i.e a value of "12,345.67" can be read as numeric `12345.67`, not simply as a string `"12,345.67"`, if the `castFormattedNumberToNumeric()` setting is enabled.
 
   This functionality is locale-aware, using the server's locale settings to identify the thousands and decimal separators.
 
-- Support for two cell anchor drawing of images. [#2532](https://github.com/PHPOffice/PhpSpreadsheet/pull/2532)
+- Support for two cell anchor drawing of images. [#2532](https://github.com/PHPOffice/PhpSpreadsheet/pull/2532) [#2674](https://github.com/PHPOffice/PhpSpreadsheet/pull/2674)
 - Limited support for Xls Reader to handle Conditional Formatting:
 
   Ranges and Rules are read, but style is currently limited to font size, weight and color; and to fill style and color.
 
+- Add ability to suppress Mac line ending check for CSV [#2623](https://github.com/PHPOffice/PhpSpreadsheet/pull/2623)
+- Initial support for creating and writing Tables (Xlsx Writer only) [PR #2671](https://github.com/PHPOffice/PhpSpreadsheet/pull/2671)
+
+  See `/samples/Table` for examples of use.
+
+  Note that PreCalculateFormulas needs to be disabled when saving spreadsheets containing tables with formulae (totals or column formulae).
+
 ### Changed
 
 - Gnumeric Reader now loads number formatting for cells.
@@ -37,26 +47,55 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 ### Deprecated
 
 - All Excel Function implementations in `Calculation\Functions` (including the Error functions) have been moved to dedicated classes for groups of related functions. See the docblocks against all the deprecated methods for details of the new methods to call instead. At some point, these old classes will be deleted.
+- Worksheet methods that reference cells "byColumnandRow". All such methods have an equivalent that references the cell by its address (e.g. '`E3'` rather than `5, 3`).
+
+  These functions now accept either a cell address string (`'E3')` or an array with columnId and rowId (`[5, 3]`) or a new `CellAddress` object as their `cellAddress`/`coordinate` argument.
+  This includes the methods:
+  - `setCellValueByColumnAndRow()` use the equivalent `setCellValue()`
+  - `setCellValueExplicitByColumnAndRow()` use the equivalent `setCellValueExplicit()`
+  - `getCellByColumnAndRow()` use the equivalent `getCell()`
+  - `cellExistsByColumnAndRow()` use the equivalent `cellExists()`
+  - `getStyleByColumnAndRow()` use the equivalent `getStyle()`
+  - `setBreakByColumnAndRow()` use the equivalent `setBreak()`
+  - `mergeCellsByColumnAndRow()` use the equivalent `mergeCells()`
+  - `unmergeCellsByColumnAndRow()` use the equivalent `unmergeCells()`
+  - `protectCellsByColumnAndRow()` use the equivalent `protectCells()`
+  - `unprotectCellsByColumnAndRow()` use the equivalent `unprotectCells()`
+  - `setAutoFilterByColumnAndRow()` use the equivalent `setAutoFilter()`
+  - `freezePaneByColumnAndRow()` use the equivalent `freezePane()`
+  - `getCommentByColumnAndRow()` use the equivalent `getComment()`
+  - `setSelectedCellByColumnAndRow()` use the equivalent `setSelectedCells()`
+
+  This change provides more consistency in the methods (not every "by cell address" method has an equivalent "byColumnAndRow" method);
+  and the "by cell address" methods often provide more flexibility, such as allowing a range of cells, or referencing them by passing the defined name of a named range as the argument.
 
 ### Removed
 
 - Nothing
 
 ### Fixed
 
+- Make allowance for the AutoFilter dropdown icon in the first row of an Autofilter range when using Autosize columns. [Issue #2413](https://github.com/PHPOffice/PhpSpreadsheet/issues/2413) [PR #2754](https://github.com/PHPOffice/PhpSpreadsheet/pull/2754)
+- Support for "chained" ranges (e.g. `A5:C10:C20:F1`) in the Calculation Engine; and also support for using named ranges with the Range operator (e.g. `NamedRange1:NamedRange2`) [Issue #2730](https://github.com/PHPOffice/PhpSpreadsheet/issues/2730) [PR #2746](https://github.com/PHPOffice/PhpSpreadsheet/pull/2746)
 - Update Conditional Formatting ranges and rule conditions when inserting/deleting rows/columns [Issue #2678](https://github.com/PHPOffice/PhpSpreadsheet/issues/2678) [PR #2689](https://github.com/PHPOffice/PhpSpreadsheet/pull/2689)
 - Allow `INDIRECT()` to accept row/column ranges as well as cell ranges [PR #2687](https://github.com/PHPOffice/PhpSpreadsheet/pull/2687)
 - Fix bug when deleting cells with hyperlinks, where the hyperlink was then being "inherited" by whatever cell moved to that cell address.
 - Fix bug in Conditional Formatting in the Xls Writer that resulted in a broken file when there were multiple conditional ranges in a worksheet.
 - Fix Conditional Formatting in the Xls Writer to work with rules that contain string literals, cell references and formulae.
 - Fix for setting Active Sheet to the first loaded worksheet when bookViews element isn't defined [Issue #2666](https://github.com/PHPOffice/PhpSpreadsheet/issues/2666) [PR #2669](https://github.com/PHPOffice/PhpSpreadsheet/pull/2669)
-- Fixed behaviour of XLSX font style vertical align settings.
+- Fixed behaviour of XLSX font style vertical align settings [PR #2619](https://github.com/PHPOffice/PhpSpreadsheet/pull/2619)
 - Resolved formula translations to handle separators (row and column) for array functions as well as for function argument separators; and cleanly handle nesting levels.
 
   Note that this method is used when translating Excel functions between `en_us` and other locale languages, as well as when converting formulae between different spreadsheet formats (e.g. Ods to Excel).
 
   Nor is this a perfect solution, as there may still be issues when function calls have array arguments that themselves contain function calls; but it's still better than the current logic.
 - Fix for escaping double quotes within a formula [Issue #1971](https://github.com/PHPOffice/PhpSpreadsheet/issues/1971) [PR #2651](https://github.com/PHPOffice/PhpSpreadsheet/pull/2651)
+- Change open mode for output from `wb+` to `wb` [Issue #2372](https://github.com/PHPOffice/PhpSpreadsheet/issues/2372) [PR #2657](https://github.com/PHPOffice/PhpSpreadsheet/pull/2657)
+- Use color palette if supplied [Issue #2499](https://github.com/PHPOffice/PhpSpreadsheet/issues/2499) [PR #2595](https://github.com/PHPOffice/PhpSpreadsheet/pull/2595)
+- Xls reader treat drawing offsets as int rather than float [PR #2648](https://github.com/PHPOffice/PhpSpreadsheet/pull/2648)
+- Handle booleans in conditional styles properly [PR #2654](https://github.com/PHPOffice/PhpSpreadsheet/pull/2654)
+- Fix for reading files in the root directory of a ZipFile, which should not be prefixed by relative paths ("./") as dirname($filename) does by default. 
+- Fix invalid style of cells in empty columns with columnDimensions and rows with rowDimensions in added external sheet. [PR #2739](https://github.com/PHPOffice/PhpSpreadsheet/pull/2739)
 
 ## 1.22.0 - 2022-02-18
 

docs/topics/file-formats.md

@@ -80,7 +80,8 @@ semi-colon (`;`) are used as separators instead of a comma, although
 other symbols can be used. Because CSV is a text-only format, it doesn't
 support any data formatting options.
 
-"CSV" is not a single, well-defined format (although see RFC 4180 for
+"CSV" is not a single, well-defined format (although see 
+[RFC 4180](https://www.rfc-editor.org/rfc/rfc4180.html) for
 one definition that is commonly used). Rather, in practice the term
 "CSV" refers to any file that:
 
@@ -117,5 +118,5 @@ Wide Web Consortium (W3C). However, in 2000, HTML also became an
 international standard (ISO/IEC 15445:2000). HTML 4.01 was published in
 late 1999, with further errata published through 2001. In 2004
 development began on HTML5 in the Web Hypertext Application Technology
-Working Group (WHATWG), which became a joint deliverable with the W3C in
-2008.
+Working Group (WHATWG), which became a joint deliverable with the W3C in 2008.
+

docs/topics/reading-files.md

@@ -44,6 +44,22 @@ practise), it will reject the Xls loader that it would normally use for
 a .xls file; and test the file using the other loaders until it finds
 the appropriate loader, and then use that to read the file.
 
+If you know that this is an `xls` file, but don't know whether it is a
+genuine BIFF-format Excel or Html markup with an xls extension, you can
+limit the loader to check only those two possibilities by passing in an
+array of Readers to test against.
+
+```php
+$inputFileName = './sampleData/example1.xls';
+$testAgainstFormats = [
+    \PhpOffice\PhpSpreadsheet\IOFactory::READER_XLS,
+    \PhpOffice\PhpSpreadsheet\IOFactory::READER_HTML,
+];
+
+/** Load $inputFileName to a Spreadsheet Object  **/
+$spreadsheet = \PhpOffice\PhpSpreadsheet\IOFactory::load($inputFileName, 0, $testAgainstFormats);
+```
+
 While easy to implement in your code, and you don't need to worry about
 the file type; this isn't the most efficient method to load a file; and
 it lacks the flexibility to configure the loader in any way before
@@ -118,6 +134,34 @@ $spreadsheet = $reader->load($inputFileName);
 See `samples/Reader/04_Simple_file_reader_using_the_IOFactory_to_identify_a_reader_to_use.php`
 for a working example of this code.
 
+As with the IOFactory `load()` method, you can also pass an array of formats
+for  the `identify()` method to check against if you know that it will only
+be in a subset of the possible formats that PhpSpreadsheet supports.
+
+```php
+$inputFileName = './sampleData/example1.xls';
+$testAgainstFormats = [
+    \PhpOffice\PhpSpreadsheet\IOFactory::READER_XLS,
+    \PhpOffice\PhpSpreadsheet\IOFactory::READER_HTML,
+];
+
+/**  Identify the type of $inputFileName  **/
+$inputFileType = \PhpOffice\PhpSpreadsheet\IOFactory::identify($inputFileName, $testAgainstFormats);
+```
+
+You can also use this to confirm that a file is what it claims to be:
+
+```php
+$inputFileName = './sampleData/example1.xls';
+
+try {
+    /**  Verify that $inputFileName really is an Xls file **/
+    $inputFileType = \PhpOffice\PhpSpreadsheet\IOFactory::identify($inputFileName, [\PhpOffice\PhpSpreadsheet\IOFactory::READER_XLS]);
+} catch (\PhpOffice\PhpSpreadsheet\Reader\Exception $e) {
+    // File isn't actually an Xls file, even though it has an xls extension 
+}
+```
+
 ## Spreadsheet Reader Options
 
 Once you have created a reader object for the workbook that you want to
@@ -146,7 +190,7 @@ $spreadsheet = $reader->load($inputFileName);
 See `samples/Reader/05_Simple_file_reader_using_the_read_data_only_option.php`
 for a working example of this code.
 
-It is important to note that Workbooks (and PhpSpreadsheet) store dates
+It is important to note that most Workbooks (and PhpSpreadsheet) store dates
 and times as simple numeric values: they can only be distinguished from
 other numeric values by the format mask that is applied to that cell.
 When setting read data only to true, PhpSpreadsheet doesn't read the
@@ -162,8 +206,8 @@ Reading Only Data from a Spreadsheet File applies to Readers:
 
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N |
 ----------|:---:|--------|:---:|--------------|:---:|
-Xlsx      | YES | Xls | YES | Xml | YES |
-Ods    | YES | SYLK   | NO  | Gnumeric     | YES |
+Xlsx      | YES | Xls    | YES | Xml          | YES |
+Ods       | YES | SYLK   | NO  | Gnumeric     | YES |
 CSV       | NO  | HTML   | NO
 
 ### Reading Only Named WorkSheets from a File
@@ -233,8 +277,8 @@ Reading Only Named WorkSheets from a File applies to Readers:
 
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N |
 ----------|:---:|--------|:---:|--------------|:---:|
-Xlsx      | YES | Xls | YES | Xml | YES |
-Ods    | YES | SYLK   | NO  | Gnumeric     | YES |
+Xlsx      | YES | Xls    | YES | Xml          | YES |
+Ods       | YES | SYLK   | NO  | Gnumeric     | YES |
 CSV       | NO  | HTML   | NO
 
 ### Reading Only Specific Columns and Rows from a File (Read Filters)
@@ -381,7 +425,7 @@ Using Read Filters applies to:
 
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N |
 ----------|:---:|--------|:---:|--------------|:---:|
-Xlsx      | YES | Xls    | YES | Xml | YES |
+Xlsx      | YES | Xls    | YES | Xml          | YES |
 Ods       | YES | SYLK   | NO  | Gnumeric     | YES |
 CSV       | YES | HTML   | NO  |              |     |
 
@@ -439,7 +483,7 @@ Combining Multiple Files into a Single Spreadsheet Object applies to:
 
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N |
 ----------|:---:|--------|:---:|--------------|:---:|
-Xlsx      | NO  | Xls    | NO  | Xml | NO  |
+Xlsx      | NO  | Xls    | NO  | Xml          | NO  |
 Ods       | NO  | SYLK   | YES | Gnumeric     | NO  |
 CSV       | YES | HTML   | NO
 
@@ -516,7 +560,7 @@ Splitting a single loaded file across multiple worksheets applies to:
 
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N |
 ----------|:---:|--------|:---:|--------------|:---:|
-Xlsx      | NO  | Xls    | NO  | Xml | NO  |
+Xlsx      | NO  | Xls    | NO  | Xml          | NO  |
 Ods       | NO  | SYLK   | NO  | Gnumeric     | NO  |
 CSV       | YES | HTML   | NO
 
@@ -556,7 +600,7 @@ Setting CSV delimiter applies to:
 
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N |
 ----------|:---:|--------|:---:|--------------|:---:|
-Xlsx      | NO  | Xls    | NO  | Xml | NO  |
+Xlsx      | NO  | Xls    | NO  | Xml          | NO  |
 Ods       | NO  | SYLK   | NO  | Gnumeric     | NO  |
 CSV       | YES | HTML   | NO
 
@@ -594,7 +638,7 @@ Applies to:
 
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N |
 ----------|:---:|--------|:---:|--------------|:---:|
-Xlsx      | NO  | Xls    | NO  | Xml | NO  |
+Xlsx      | NO  | Xls    | NO  | Xml          | NO  |
 Ods       | NO  | SYLK   | NO  | Gnumeric     | NO  |
 CSV       | YES | HTML   | NO
 
@@ -646,7 +690,7 @@ Loading using a Value Binder applies to:
 
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N
 ----------|:---:|--------|:---:|--------------|:---:
-Xlsx      | NO  | Xls    | NO  | Xml | NO
+Xlsx      | NO  | Xls    | NO  | Xml          | NO
 Ods       | NO  | SYLK   | NO  | Gnumeric     | NO
 CSV       | YES | HTML   | YES
 

docs/topics/recipes.md

@@ -1167,13 +1167,15 @@ that you are setting is measured in.
 Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches),
 `cm` (centimeters) and `mm` (millimeters).
 
+Setting the column width to `-1` tells MS Excel to display the column using its default width.  
+
 ```php
 $spreadsheet->getActiveSheet()->getColumnDimension('D')->setWidth(120, 'pt');
 ```
 
 If you want PhpSpreadsheet to perform an automatic width calculation,
-use the following code. PhpSpreadsheet will approximate the column with
-to the width of the widest column value.
+use the following code. PhpSpreadsheet will approximate the column width
+to the width of the widest value displayed in that column.
 
 ```php
 $spreadsheet->getActiveSheet()->getColumnDimension('B')->setAutoSize(true);
@@ -1266,6 +1268,18 @@ Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches),
 $spreadsheet->getActiveSheet()->getRowDimension('10')->setRowHeight(100, 'pt');
 ```
 
+Setting the row height to `-1` tells MS Excel to display the column using its default height, which is based on the character font size.
+
+If you have wrapped text in a cell, then the `-1` default will only set the row height to display a single line of that wrapped text.
+If you need to calculate the actual height for the row, then count the lines that should be displayed (count the `\n` and add 1); then adjust for the font.
+The adjustment for Calibri 11 is approximately 14.5; for Calibri 12 15.9, etc.
+```php
+$spreadsheet->getActiveSheet()->getRowDimension(1)->setRowHeight(
+    14.5 * (substr_count($sheet->getCell('A1')->getValue(), "\n") + 1)
+);
+```
+
+
 ## Show/hide a row
 
 To set a worksheet''s row visibility, you can use the following code.