Merge branch 'master' into moredatefilter

Author: oleibman

CHANGELOG.md

@@ -9,7 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
-- Nothing.
+- Support for passing flags in the Reader `load()` and Writer `save()`methods, and through the IOFactory, to set behaviours. [PR #2136](https://github.com/PHPOffice/PhpSpreadsheet/pull/2136)
+  - See [documentation](https://phpspreadsheet.readthedocs.io/en/latest/topics/reading-and-writing-to-file/) for details
+- More flexibility in the StringValueBinder to determine what datatypes should be treated as strings [PR #2138](https://github.com/PHPOffice/PhpSpreadsheet/pull/2138)
+- Helper class for conversion between css size Units of measure (`px`, `pt`, `pc`, `in`, `cm`, `mm`). [PR #2152](https://github.com/PHPOffice/PhpSpreadsheet/issues/2145)
+- Allow Row height and Column Width to be set using different units of measure (`px`, `pt`, `pc`, `in`, `cm`, `mm`), rather than only in points or MS Excel column width units. [PR #2152](https://github.com/PHPOffice/PhpSpreadsheet/issues/2145)
 
 ### Changed
 
@@ -25,7 +29,9 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Fixed
 
-- Nothing.
+- Xls Reader changing grey background to black in Excel template [Issue #2147](Changing grey background to black in Excel template) [PR #2156](https://github.com/PHPOffice/PhpSpreadsheet/pull/2156)
+- Column width and Row height styles in the Html Reader when the value includes a unit of measure. [Issue #2145](https://github.com/PHPOffice/PhpSpreadsheet/issues/2145).
+
 
 ## 1.18.0 - 2021-05-31
 

docs/topics/accessing-cells.md

@@ -110,6 +110,11 @@ values beginning with `=` will be converted to a formula. Strings that
 aren't numeric, or that don't begin with a leading `=` will be treated
 as genuine string values.
 
+Note that a numeric string that begins with a leading zero (that isn't
+immediately followed by a decimal separator) will not be converted to a
+numeric, so values like phone numbers (e.g. `01615991375``will remain as
+strings).
+
 This "conversion" is handled by a cell "value binder", and you can write
 custom "value binders" to change the behaviour of these "conversions".
 The standard PhpSpreadsheet package also provides an "advanced value
@@ -138,8 +143,10 @@ Formats handled by the advanced value binder include:
 - When strings contain a newline character (`\n`), then the cell styling is
   set to wrap.
 
-You can read more about value binders later in this section of the
-documentation.
+Basically, it attempts to mimic the behaviour of the MS Excel GUI.
+
+You can read more about value binders [later in this section of the
+documentation](#using-value-binders-to-facilitate-data-entry).
 
 ### Setting a formula in a Cell
 
@@ -551,8 +558,27 @@ $spreadsheet->getActiveSheet()->setCellValue('A5', 'Date/time value:');
 $spreadsheet->getActiveSheet()->setCellValue('B5', '21 December 1983');
 ```
 
-**Creating your own value binder is easy.** When advanced value binding
-is required, you can implement the
-`\PhpOffice\PhpSpreadsheet\Cell\IValueBinder` interface or extend the
+Alternatively, a `\PhpOffice\PhpSpreadsheet\Cell\StringValueBinder` class is available
+if you want to preserve all content as strings. This might be appropriate if you
+were loading a file containing values that could be interpreted as numbers (e.g. numbers
+with leading sign such as international phone numbers like `+441615579382`), but that
+should be retained as strings (non-international phone numbers with leading zeroes are
+already maintained as strings).
+
+By default, the StringValueBinder will cast any datatype passed to it into a string. However, there are a number of settings which allow you to specify that certain datatypes shouldn't be cast to strings, but left "as is":
+
+```php
+// Set value binder
+$stringValueBinder = new \PhpOffice\PhpSpreadsheet\Cell\StringValueBinder();
+$stringValueBinder->setNumericConversion(false)
+    ->setBooleanConversion(false)
+    ->setNullConversion(false)
+    ->setFormulaConversion(false);
+\PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( $stringValueBinder );
+```
+
+**Creating your own value binder is relatively straightforward.** When more specialised
+value binding is required, you can implement the
+`\PhpOffice\PhpSpreadsheet\Cell\IValueBinder` interface or extend the existing
 `\PhpOffice\PhpSpreadsheet\Cell\DefaultValueBinder` or
 `\PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder` classes.

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

@@ -1,8 +1,7 @@
 # Reading and writing to file
 
 As you already know from the [architecture](./architecture.md#readers-and-writers),
-reading and writing to a
-persisted storage is not possible using the base PhpSpreadsheet classes.
+reading and writing to a persisted storage is not possible using the base PhpSpreadsheet classes.
 For this purpose, PhpSpreadsheet provides readers and writers, which are
 implementations of `\PhpOffice\PhpSpreadsheet\Reader\IReader` and
 `\PhpOffice\PhpSpreadsheet\Writer\IWriter`.
@@ -892,8 +891,7 @@ class My_Custom_TCPDF_Writer extends \PhpOffice\PhpSpreadsheet\Writer\Pdf\Tcpdf
 
 #### Writing a spreadsheet
 
-Once you have identified the Renderer that you wish to use for PDF
-generation, you can write a .pdf file using the following code:
+Once you have identified the Renderer that you wish to use for PDF generation, you can write a .pdf file using the following code:
 
 ```php
 $writer = new \PhpOffice\PhpSpreadsheet\Writer\Pdf\Mpdf($spreadsheet);
@@ -905,8 +903,7 @@ first worksheet by default.
 
 #### Write all worksheets
 
-PDF files can contain one or more worksheets. If you want to write all
-sheets into a single PDF file, use the following code:
+PDF files can contain one or more worksheets. If you want to write all sheets into a single PDF file, use the following code:
 
 ```php
 $writer->writeAllSheets();
@@ -1020,3 +1017,64 @@ $spreadhseet = $reader->loadFromString($secondHtmlString, $spreadsheet);
 $writer = \PhpOffice\PhpSpreadsheet\IOFactory::createWriter($spreadsheet, 'Xls');
 $writer->save('write.xls');
 ```
+
+## Reader/Writer Flags
+
+Some Readers and Writers support special "Feature Flags" that need to be explicitly enabled.
+An example of this is Charts in a spreadsheet. By default, when you load a spreadsheet that contains Charts, the charts will not be loaded. If all you want to do is read the data in the spreadsheet, then loading charts is an overhead for both speed of loading and memory usage.
+However, there are times when you may want to load any charts in the spreadsheet as well as the data. To do so, you need to tell the Reader explicitly to include Charts.
+
+```php
+$reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReaderForFile("05featuredemo.xlsx");
+$reader->setIncludeCharts(true);
+$reader->load("spreadsheetWithCharts.xlsx");
+```
+Alternatively, you can specify this in the call to load the spreadsheet:
+```php
+$reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReaderForFile("spreadsheetWithCharts.xlsx");
+$reader->load("spreadsheetWithCharts.xlsx", $reader::LOAD_WITH_CHARTS);
+```
+
+If you wish to use the IOFactory `load()` method rather than instantiating a specific Reader, then you can still pass these flags.
+
+```php
+$spreadsheet = \PhpOffice\PhpSpreadsheet\IOFactory::load("spreadsheetWithCharts.xlsx", \PhpOffice\PhpSpreadsheet\Reader\IReader::LOAD_WITH_CHARTS);
+```
+
+Likewise, when saving a file using a Writer, loaded charts wil not be saved unless you explicitly tell the Writer to include them:
+
+```php
+$writer = IOFactory::createWriter($spreadsheet, 'Xlsx');
+$writer->setIncludeCharts(true);
+$writer->save('mySavedFileWithCharts.xlsx');
+```
+
+As with the `load()` method, you can also pass flags in the `save()` method:
+```php
+$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.
+
+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 |
+--------|------------------|
+Xlsx    |        YES       |
+Xls     |        NO        |
+Ods     |        NO        |
+Html    |        YES       |
+Pdf     |        YES       |
+Csv     |        N/A       |
+

docs/topics/recipes.md

@@ -1122,6 +1122,16 @@ A column's width can be set using the following code:
 $spreadsheet->getActiveSheet()->getColumnDimension('D')->setWidth(12);
 ```
 
+If you want to set a column width using a different unit of measure,
+then you can do so by telling PhpSpreadsheet what UoM the width value
+that you are setting is measured in.
+Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches),
+`cm` (centimeters) and `mm` (millimeters).
+
+```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.
@@ -1207,6 +1217,16 @@ Excel measures row height in points, where 1 pt is 1/72 of an inch (or
 about 0.35mm). The default value is 12.75 pts; and the permitted range
 of values is between 0 and 409 pts, where 0 pts is a hidden row.
 
+If you want to set a row height using a different unit of measure,
+then you can do so by telling PhpSpreadsheet what UoM the height value
+that you are setting is measured in.
+Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches),
+`cm` (centimeters) and `mm` (millimeters).
+
+```php
+$spreadsheet->getActiveSheet()->getRowDimension('10')->setRowHeight(100, 'pt');
+```
+
 ## Show/hide a row
 
 To set a worksheet''s row visibility, you can use the following code.
@@ -1560,6 +1580,20 @@ Default column width can be set using the following code:
 $spreadsheet->getActiveSheet()->getDefaultColumnDimension()->setWidth(12);
 ```
 
+Excel measures column width in its own proprietary units, based on the number
+of characters that will be displayed in the default font.
+
+If you want to set the default column width using a different unit of measure,
+then you can do so by telling PhpSpreadsheet what UoM the width value
+that you are setting is measured in.
+Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches),
+`cm` (centimeters) and `mm` (millimeters).
+
+```php
+$spreadsheet->getActiveSheet()->getDefaultColumnDimension()->setWidth(400, 'pt');
+```
+and PhpSpreadsheet will handle the internal conversion.
+
 ## Setting the default row height
 
 Default row height can be set using the following code:
@@ -1568,6 +1602,21 @@ Default row height can be set using the following code:
 $spreadsheet->getActiveSheet()->getDefaultRowDimension()->setRowHeight(15);
 ```
 
+Excel measures row height in points, where 1 pt is 1/72 of an inch (or
+about 0.35mm). The default value is 12.75 pts; and the permitted range
+of values is between 0 and 409 pts, where 0 pts is a hidden row.
+
+If you want to set a row height using a different unit of measure,
+then you can do so by telling PhpSpreadsheet what UoM the height value
+that you are setting is measured in.
+Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches),
+`cm` (centimeters) and `mm` (millimeters).
+
+```php
+$spreadsheet->getActiveSheet()->getDefaultRowDimension()->setRowHeight(100, 'pt');
+```
+
+
 ## Add a GD drawing to a worksheet
 
 There might be a situation where you want to generate an in-memory image

phpstan-baseline.neon

@@ -2487,7 +2487,7 @@ parameters:
 
 		-
 			message: "#^Parameter \\#3 \\$subject of function str_replace expects array\\|string, string\\|null given\\.$#"
-			count: 4
+			count: 2
 			path: src/PhpSpreadsheet/Reader/Html.php
 
 		-
@@ -2775,11 +2775,6 @@ parameters:
 			count: 1
 			path: src/PhpSpreadsheet/Reader/Xls.php
 
-		-
-			message: "#^Parameter \\#1 \\$value of method PhpOffice\\\\PhpSpreadsheet\\\\Worksheet\\\\MemoryDrawing\\:\\:setImageResource\\(\\) expects GdImage\\|resource, resource\\|false given\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Reader/Xls.php
-
 		-
 			message: "#^Parameter \\#1 \\$pValue of method PhpOffice\\\\PhpSpreadsheet\\\\Worksheet\\\\BaseDrawing\\:\\:setOffsetX\\(\\) expects int, float\\|int given\\.$#"
 			count: 1
@@ -4100,11 +4095,6 @@ parameters:
 			count: 1
 			path: src/PhpSpreadsheet/Shared/Date.php
 
-		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Shared\\\\Drawing\\:\\:pixelsToCellDimension\\(\\) should return int but returns float\\|int\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Shared/Drawing.php
-
 		-
 			message: "#^Parameter \\#1 \\$fp of function fread expects resource, resource\\|false given\\.$#"
 			count: 2
@@ -4240,11 +4230,6 @@ parameters:
 			count: 1
 			path: src/PhpSpreadsheet/Shared/Font.php
 
-		-
-			message: "#^Parameter \\#1 \\$pValue of static method PhpOffice\\\\PhpSpreadsheet\\\\Shared\\\\Drawing\\:\\:pixelsToCellDimension\\(\\) expects int, float\\|int given\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Shared/Font.php
-
 		-
 			message: "#^Parameter \\#2 \\$pDefaultFont of static method PhpOffice\\\\PhpSpreadsheet\\\\Shared\\\\Drawing\\:\\:pixelsToCellDimension\\(\\) expects PhpOffice\\\\PhpSpreadsheet\\\\Style\\\\Font, PhpOffice\\\\PhpSpreadsheet\\\\Style\\\\Font\\|null given\\.$#"
 			count: 1
@@ -4860,16 +4845,6 @@ parameters:
 			count: 1
 			path: src/PhpSpreadsheet/Shared/XMLWriter.php
 
-		-
-			message: "#^Parameter \\#1 \\$pValue of static method PhpOffice\\\\PhpSpreadsheet\\\\Shared\\\\Drawing\\:\\:pointsToPixels\\(\\) expects int, float given\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Shared/Xls.php
-
-		-
-			message: "#^Parameter \\#1 \\$fontSizeInPoints of static method PhpOffice\\\\PhpSpreadsheet\\\\Shared\\\\Font\\:\\:fontSizeToPixels\\(\\) expects int, float given\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Shared/Xls.php
-
 		-
 			message: "#^Property PhpOffice\\\\PhpSpreadsheet\\\\Spreadsheet\\:\\:\\$workbookViewVisibilityValues has no typehint specified\\.$#"
 			count: 1
@@ -6215,11 +6190,6 @@ parameters:
 			count: 1
 			path: src/PhpSpreadsheet/Writer/Html.php
 
-		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Writer\\\\IWriter\\:\\:save\\(\\) has no return typehint specified\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Writer/IWriter.php
-
 		-
 			message: "#^Negated boolean expression is always false\\.$#"
 			count: 1