| 1 |
Upgrading from 2.x to 3.0 |
| 2 |
========================= |
| 3 |
|
| 4 |
Spout 3.0 introduced several backwards-incompatible changes. The upgrade from Spout 2.x to 3.0 must therefore be done with caution. |
| 5 |
This guide is meant to ease this process. |
| 6 |
|
| 7 |
Most notable changes |
| 8 |
-------------------- |
| 9 |
In 2.x, styles were applied per row; it was therefore impossible to apply different styles to cells in the same row. |
| 10 |
With the 3.0 version, this is now possible: each cell can have its own style. |
| 11 |
|
| 12 |
Spout 3.0 tries to enforce better typing. For instance, instead of using/returning generic arrays, Spout now makes use of specific `Row` and `Cell` objects that can encapsulate more data such as type, style, value. |
| 13 |
|
| 14 |
Finally, **_Spout 3.2 only supports PHP 7.2 and above_**, as other PHP versions are no longer supported by the community. |
| 15 |
|
| 16 |
Reader changes |
| 17 |
-------------- |
| 18 |
Creating a reader should now be done through the Reader `ReaderEntityFactory`, instead of using the `ReaderFactory`. |
| 19 |
Also, the `ReaderFactory::create($type)` method was removed and replaced by methods for each reader: |
| 20 |
```php |
| 21 |
use OpenSpout\Reader\Common\Creator\ReaderEntityFactory; // namespace is no longer "OpenSpout\Reader" |
| 22 |
... |
| 23 |
$reader = ReaderEntityFactory::createXLSXReader(); // replaces ReaderFactory::create(Type::XLSX) |
| 24 |
$reader = ReaderEntityFactory::createCSVReader(); // replaces ReaderFactory::create(Type::CSV) |
| 25 |
$reader = ReaderEntityFactory::createODSReader(); // replaces ReaderFactory::create(Type::ODS) |
| 26 |
``` |
| 27 |
|
| 28 |
When iterating over the spreadsheet rows, Spout now returns `Row` objects, instead of an array containing row values. Accessing the row values should now be done this way: |
| 29 |
```php |
| 30 |
... |
| 31 |
foreach ($reader->getSheetIterator() as $sheet) { |
| 32 |
foreach ($sheet->getRowIterator() as $row) { // $row is a "Row" object, not an array |
| 33 |
$rowAsArray = $row->toArray(); // this is the 2.x equivalent |
| 34 |
// OR |
| 35 |
$cellsArray = $row->getCells(); // this can be used to get access to cells' details |
| 36 |
... |
| 37 |
} |
| 38 |
} |
| 39 |
``` |
| 40 |
|
| 41 |
Writer changes |
| 42 |
-------------- |
| 43 |
Writer creation follows the same change as the reader. It should now be done through the Writer `WriterEntityFactory`, instead of using the `WriterFactory`. |
| 44 |
Also, the `WriterFactory::create($type)` method was removed and replaced by methods for each writer: |
| 45 |
|
| 46 |
```php |
| 47 |
use OpenSpout\Writer\Common\Creator\WriterEntityFactory; // namespace is no longer "OpenSpout\Writer" |
| 48 |
... |
| 49 |
$writer = WriterEntityFactory::createXLSXWriter(); // replaces WriterFactory::create(Type::XLSX) |
| 50 |
$writer = WriterEntityFactory::createCSVWriter(); // replaces WriterFactory::create(Type::CSV) |
| 51 |
$writer = WriterEntityFactory::createODSWriter(); // replaces WriterFactory::create(Type::ODS) |
| 52 |
``` |
| 53 |
|
| 54 |
Adding rows is also done differently: instead of passing an array, the writer now takes in a `Row` object (or an array of `Row`). Creating such objects can easily be done this way: |
| 55 |
```php |
| 56 |
// Adding a row from an array of values (2.x equivalent) |
| 57 |
$cellValues = ['foo', 12345]; |
| 58 |
$row1 = WriterEntityFactory::createRowFromArray($cellValues, $rowStyle); |
| 59 |
|
| 60 |
// Adding a row from an array of Cell |
| 61 |
$cell1 = WriterEntityFactory::createCell('foo', $cellStyle1); // this cell has its own style |
| 62 |
$cell2 = WriterEntityFactory::createCell(12345, $cellStyle2); // this cell has its own style |
| 63 |
$row2 = WriterEntityFactory::createRow([$cell1, $cell2]); |
| 64 |
|
| 65 |
$writer->addRows([$row1, $row2]); |
| 66 |
``` |
| 67 |
|
| 68 |
Namespace changes for styles |
| 69 |
----------------- |
| 70 |
The namespaces for styles have changed. Styles are still created by using a `builder` class. |
| 71 |
|
| 72 |
For the builder, please update your import statements to use the following namespaces: |
| 73 |
|
| 74 |
OpenSpout\Writer\Common\Creator\Style\StyleBuilder |
| 75 |
OpenSpout\Writer\Common\Creator\Style\BorderBuilder |
| 76 |
|
| 77 |
The `Style` base class and style definitions like `Border`, `BorderPart` and `Color` also have a new namespace. |
| 78 |
|
| 79 |
If your are using these classes directly via an import statement in your code, please use the following namespaces: |
| 80 |
|
| 81 |
OpenSpout\Common\Entity\Style\Border |
| 82 |
OpenSpout\Common\Entity\Style\BorderPart |
| 83 |
OpenSpout\Common\Entity\Style\Color |
| 84 |
OpenSpout\Common\Entity\Style\Style |
| 85 |
|
| 86 |
Handling of empty rows |
| 87 |
---------------------- |
| 88 |
In 2.x, empty rows were not added to the spreadsheet. |
| 89 |
In 3.0, `addRow` now always writes a row to the spreadsheet: when the row does not contain any cells, an empty row is created in the sheet. |
| 90 |
|
