Upgrade to 3.0 guide

UPGRADE-3.0.md

@@ -1,6 +1,64 @@
-# Migrate from 2.x to 3.0
+Upgrading from 2.x to 3.0
+=========================
 
-## Handling of empty rows
+Spout 3.0 introduced several backwards-incompatible changes. The upgrade from Spout 2.x to 3.0 must therefore be done with caution.
+This guide is meant to ease this process.
 
-* The handling of empty data in writers has changed. In 2.x an array was not added to the spreadsheet when ```empty($dataRow)``` evaluated to true.
+Most notable changes
-* In 3.0 a row is always written to the speadsheet. When the row does not contain any cells an empty row is created in the sheet.
+--------------------
+In 2.x, styles were applied per row; it was therefore impossible to apply different styles to cells in the same row.
+With the 3.0 version, this is now possible: each cell can have its own style.
+
+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.
+
+Finally, **_Spout 3.0 only supports PHP 7.1 and above_**, as other PHP versions are no longer supported by the community.
+
+Reader changes
+--------------
+Creating a reader should now be done through the Reader `EntityFactory`, instead of using the `ReaderFactory`:
+```php
+use Box\Spout\Reader\Common\Creator\EntityFactory; // namespace is no longer "Box\Spout\Reader"
+...
+$reader = EntityFactory::createReader(Type::XLSX);
+```
+
+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:
+```php
+...
+foreach ($reader->getSheetIterator() as $sheet) {
+    foreach ($sheet->getRowIterator() as $row) { // $row is a "Row" object, not an array
+        $rowAsArray = $row->toArray();  // this is the 2.x equivalent
+        // OR
+        $cellsArray = $row->getCells(); // this can be used to get access to cells' details
+        ... 
+    }
+}
+```
+
+Writer changes
+--------------
+Writer creation follows the same change as the reader. It should now be done through the Writer `EntityFactory`, instead of using the `WriterFactory`:
+```php
+use Box\Spout\Writer\Common\Creator\EntityFactory; // namespace is no longer "Box\Spout\Writer"
+...
+$writer = EntityFactory::createWriter(Type::ODS);
+```
+
+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:
+```php
+// Adding a row from an array of values (2.x equivalent)
+$cellValues = ['foo', 12345];
+$row1 = EntityFactory::createRowFromArray($cellValues, $rowStyle);
+
+// Adding a row from an array of Cell
+$cell1 = EntityFactory::createCell('foo', $cellStyle1); // this cell has its own style
+$cell2 = EntityFactory::createCell(12345, $cellStyle2); // this cell has its own style
+$row2 = EntityFactory::createRow([$cell1, $cell2]);
+
+$writer->addRows([$row1, $row2]);
+```
+
+Handling of empty rows
+----------------------
+In 2.x, empty rows were not added to the spreadsheet.
+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.