visualizer / vendor / phpoffice / phpspreadsheet / docs / topics / migration-from-PHPExcel.md

migration-from-PHPExcel.md in Visualizer – Tables & Charts Manager with Built-in AI Generator 3.10.5, at vendor/phpoffice/phpspreadsheet/docs/topics/migration-from-PHPExcel.md

434 lines 11.4 KB

Raw Download Zip

1	# Migration from PHPExcel
2
3	PhpSpreadsheet introduced many breaking changes by introducing
4	namespaces and renaming some classes. To help you migrate existing
5	project, a tool was written to replace all references to PHPExcel
6	classes to their new names. But there are also manual changes that
7	need to be done.
8
9	## Automated tool
10
11	The tool is included in PhpSpreadsheet. It scans recursively all files
12	and directories, starting from the current directory. Assuming it was
13	installed with composer, it can be run like so:
14
15	``` sh
16	cd /project/to/migrate/src
17	/project/to/migrate/vendor/phpoffice/phpspreadsheet/bin/migrate-from-phpexcel
18	```
19
20	Important The tool will irreversibly modify your sources, be sure to
21	backup everything, and double check the result before committing.
22
23	## Manual changes
24
25	In addition to automated changes, a few things need to be migrated manually.
26
27	### Renamed readers and writers
28
29	When using `IOFactory::createReader()`, `IOFactory::createWriter()` and
30	`IOFactory::identify()`, the reader/writer short names are used. Those were
31	changed, along as their corresponding class, to remove ambiguity:
32
33	Before \| After
34	-----------------\|---------
35	`'CSV'` \| `'Csv'`
36	`'Excel2003XML'` \| `'Xml'`
37	`'Excel2007'` \| `'Xlsx'`
38	`'Excel5'` \| `'Xls'`
39	`'Gnumeric'` \| `'Gnumeric'`
40	`'HTML'` \| `'Html'`
41	`'OOCalc'` \| `'Ods'`
42	`'OpenDocument'` \| `'Ods'`
43	`'PDF'` \| `'Pdf'`
44	`'SYLK'` \| `'Slk'`
45
46	### Simplified IOFactory
47
48	The following methods :
49
50	- `PHPExcel_IOFactory::getSearchLocations()`
51	- `PHPExcel_IOFactory::setSearchLocations()`
52	- `PHPExcel_IOFactory::addSearchLocation()`
53
54	were replaced by `IOFactory::registerReader()` and `IOFactory::registerWriter()`. That means
55	IOFactory now relies on classes autoloading.
56
57	Before:
58
59	```php
60	\PHPExcel_IOFactory::addSearchLocation($type, $location, $classname);
61	```
62
63	After:
64
65	```php
66	\PhpOffice\PhpSpreadsheet\IOFactory::registerReader($type, $classname);
67	```
68
69	### Removed deprecated things
70
71	#### Worksheet::duplicateStyleArray()
72
73	``` php
74	// Before
75	$worksheet->duplicateStyleArray($styles, $range, $advanced);
76
77	// After
78	$worksheet->getStyle($range)->applyFromArray($styles, $advanced);
79	```
80
81	#### DataType::dataTypeForValue()
82
83	``` php
84	// Before
85	DataType::dataTypeForValue($value);
86
87	// After
88	DefaultValueBinder::dataTypeForValue($value);
89	```
90
91	#### Conditional::getCondition()
92
93	``` php
94	// Before
95	$conditional->getCondition();
96
97	// After
98	$conditional->getConditions()[0];
99	```
100
101	#### Conditional::setCondition()
102
103	``` php
104	// Before
105	$conditional->setCondition($value);
106
107	// After
108	$conditional->setConditions($value);
109	```
110
111	#### Worksheet::getDefaultStyle()
112
113	``` php
114	// Before
115	$worksheet->getDefaultStyle();
116
117	// After
118	$worksheet->getParent()->getDefaultStyle();
119	```
120
121	#### Worksheet::setDefaultStyle()
122
123	``` php
124	// Before
125	$worksheet->setDefaultStyle($value);
126
127	// After
128	$worksheet->getParent()->getDefaultStyle()->applyFromArray([
129	'font' => [
130	'name' => $pValue->getFont()->getName(),
131	'size' => $pValue->getFont()->getSize(),
132	],
133	]);
134
135	```
136
137	#### Worksheet::setSharedStyle()
138
139	``` php
140	// Before
141	$worksheet->setSharedStyle($sharedStyle, $range);
142
143	// After
144	$worksheet->duplicateStyle($sharedStyle, $range);
145	```
146
147	#### Worksheet::getSelectedCell()
148
149	``` php
150	// Before
151	$worksheet->getSelectedCell();
152
153	// After
154	$worksheet->getSelectedCells();
155	```
156
157	#### Writer\Xls::setTempDir()
158
159	``` php
160	// Before
161	$writer->setTempDir();
162
163	// After, there is no way to set temporary storage directory anymore
164	```
165
166	### Autoloader
167
168	The class `PHPExcel_Autoloader` was removed entirely and is replaced by composer
169	autoloading mechanism.
170
171	### Writing PDF
172
173	PDF libraries must be installed via composer. And the following methods were removed
174	and are replaced by `IOFactory::registerWriter()` instead:
175
176	- `PHPExcel_Settings::getPdfRenderer()`
177	- `PHPExcel_Settings::setPdfRenderer()`
178	- `PHPExcel_Settings::getPdfRendererName()`
179	- `PHPExcel_Settings::setPdfRendererName()`
180
181	Before:
182
183	```php
184	\PHPExcel_Settings::setPdfRendererName(PHPExcel_Settings::PDF_RENDERER_MPDF);
185	\PHPExcel_Settings::setPdfRenderer($somePath);
186	$writer = \PHPExcel_IOFactory::createWriter($spreadsheet, 'PDF');
187	```
188
189	After:
190
191	```php
192	$writer = \PhpOffice\PhpSpreadsheet\IOFactory::createWriter($spreadsheet, 'Mpdf');
193
194	// Or alternatively
195	\PhpOffice\PhpSpreadsheet\IOFactory::registerWriter('Pdf', \PhpOffice\PhpSpreadsheet\Writer\Pdf\Mpdf::class);
196	$writer = \PhpOffice\PhpSpreadsheet\IOFactory::createWriter($spreadsheet, 'Pdf');
197
198	// Or alternatively
199	$writer = new \PhpOffice\PhpSpreadsheet\Writer\Pdf\Mpdf($spreadsheet);
200	```
201
202	### Rendering charts
203
204	When rendering charts for HTML or PDF outputs, the process was also simplified. And while
205	JpGraph support is still available, it is unfortunately not up to date for latest PHP versions
206	and it will generate various warnings.
207
208	If you rely on this feature, please consider
209	contributing either patches to JpGraph or another `IRenderer` implementation (a good
210	candidate might be [](https://github.com/szymach/c-pchartCpChart](https://github.com/szymach/c-pchart](https://github.com/szymach/c-pchart)).
211
212	Before:
213
214	```php
215	$rendererName = \PHPExcel_Settings::CHART_RENDERER_JPGRAPH;
216	$rendererLibrary = 'jpgraph3.5.0b1/src/';
217	$rendererLibraryPath = '/php/libraries/Charts/' . $rendererLibrary;
218
219	\PHPExcel_Settings::setChartRenderer($rendererName, $rendererLibraryPath);
220	```
221
222	After:
223
224	Require the dependency via composer:
225
226	```sh
227	composer require jpgraph/jpgraph
228	```
229
230	And then:
231
232	```php
233	Settings::setChartRenderer(\PhpOffice\PhpSpreadsheet\Chart\Renderer\JpGraph::class);
234	```
235
236	### PclZip and ZipArchive
237
238	Support for PclZip were dropped in favor of the more complete and modern
239	[](https://php.net/manual/en/book.zip.phpPHP extension ZipArchive](https://php.net/manual/en/book.zip.php](https://php.net/manual/en/book.zip.php).
240	So the following were removed:
241
242	- `PclZip`
243	- `PHPExcel_Settings::setZipClass()`
244	- `PHPExcel_Settings::getZipClass()`
245	- `PHPExcel_Shared_ZipArchive`
246	- `PHPExcel_Shared_ZipStreamWrapper`
247
248	### Cell caching
249
250	Cell caching was heavily refactored to leverage
251	[](https://www.php-fig.org/psr/psr-16/PSR-16](https://www.php-fig.org/psr/psr-16/](https://www.php-fig.org/psr/psr-16/). That means most classes
252	related to that feature were removed:
253
254	- `PHPExcel_CachedObjectStorage_APC`
255	- `PHPExcel_CachedObjectStorage_DiscISAM`
256	- `PHPExcel_CachedObjectStorage_ICache`
257	- `PHPExcel_CachedObjectStorage_Igbinary`
258	- `PHPExcel_CachedObjectStorage_Memcache`
259	- `PHPExcel_CachedObjectStorage_Memory`
260	- `PHPExcel_CachedObjectStorage_MemoryGZip`
261	- `PHPExcel_CachedObjectStorage_MemorySerialized`
262	- `PHPExcel_CachedObjectStorage_PHPTemp`
263	- `PHPExcel_CachedObjectStorage_SQLite`
264	- `PHPExcel_CachedObjectStorage_SQLite3`
265	- `PHPExcel_CachedObjectStorage_Wincache`
266
267	In addition to that, `\PhpOffice\PhpSpreadsheet::getCellCollection()` was renamed
268	to `\PhpOffice\PhpSpreadsheet::getCoordinates()` and
269	`\PhpOffice\PhpSpreadsheet::getCellCacheController()` to
270	`\PhpOffice\PhpSpreadsheet::getCellCollection()` for clarity.
271
272	Refer to [](./memory_saving.mdthe new documentation](./memory_saving.md](./memory_saving.md) to see how to migrate.
273
274	### Dropped conditionally returned cell
275
276	For all the following methods, it is no more possible to change the type of
277	returned value. It always return the Worksheet and never the Cell or Rule:
278
279	- Worksheet::setCellValue()
280	- Worksheet::setCellValueByColumnAndRow()
281	- Worksheet::setCellValueExplicit()
282	- Worksheet::setCellValueExplicitByColumnAndRow()
283	- Worksheet::addRule()
284
285	Migration would be similar to:
286
287	``` php
288	// Before
289	$cell = $worksheet->setCellValue('A1', 'value', true);
290
291	// After
292	$cell = $worksheet->getCell('A1')->setValue('value');
293	```
294
295	### Standardized keys for styling
296
297	Array keys used for styling have been standardized for a more coherent experience.
298	It now uses the same wording and casing as the getter and setter:
299
300	```php
301	// Before
302	$style = [
303	'numberformat' => [
304	'code' => NumberFormat::FORMAT_CURRENCY_EUR_SIMPLE,
305	],
306	'font' => [
307	'strike' => true,
308	'superScript' => true,
309	'subScript' => true,
310	],
311	'alignment' => [
312	'rotation' => 90,
313	'readorder' => Alignment::READORDER_RTL,
314	'wrap' => true,
315	],
316	'borders' => [
317	'diagonaldirection' => Borders::DIAGONAL_BOTH,
318	'allborders' => [
319	'style' => Border::BORDER_THIN,
320	],
321	],
322	'fill' => [
323	'type' => Fill::FILL_GRADIENT_LINEAR,
324	'startcolor' => [
325	'argb' => 'FFA0A0A0',
326	],
327	'endcolor' => [
328	'argb' => 'FFFFFFFF',
329	],
330	],
331	];
332
333	// After
334	$style = [
335	'numberFormat' => [
336	'formatCode' => NumberFormat::FORMAT_CURRENCY_EUR_SIMPLE,
337	],
338	'font' => [
339	'strikethrough' => true,
340	'superscript' => true,
341	'subscript' => true,
342	],
343	'alignment' => [
344	'textRotation' => 90,
345	'readOrder' => Alignment::READORDER_RTL,
346	'wrapText' => true,
347	],
348	'borders' => [
349	'diagonalDirection' => Borders::DIAGONAL_BOTH,
350	'allBorders' => [
351	'borderStyle' => Border::BORDER_THIN,
352	],
353	],
354	'fill' => [
355	'fillType' => Fill::FILL_GRADIENT_LINEAR,
356	'startColor' => [
357	'argb' => 'FFA0A0A0',
358	],
359	'endColor' => [
360	'argb' => 'FFFFFFFF',
361	],
362	],
363	];
364	```
365
366	### Dedicated class to manipulate coordinates
367
368	Methods to manipulate coordinates that used to exists in `PHPExcel_Cell` were extracted
369	to a dedicated new class `\PhpOffice\PhpSpreadsheet\Cell\Coordinate`. The methods are:
370
371	- `absoluteCoordinate()`
372	- `absoluteReference()`
373	- `buildRange()`
374	- `columnIndexFromString()`
375	- `coordinateFromString()`
376	- `extractAllCellReferencesInRange()`
377	- `getRangeBoundaries()`
378	- `mergeRangesInCollection()`
379	- `rangeBoundaries()`
380	- `rangeDimension()`
381	- `splitRange()`
382	- `stringFromColumnIndex()`
383
384	### Column index based on 1
385
386	Column indexes are now based on 1. So column `A` is the index `1`. This is consistent
387	with rows starting at 1 and Excel function `COLUMN()` that returns `1` for column `A`.
388	So the code must be adapted with something like:
389
390	```php
391	// Before
392	$cell = $worksheet->getCellByColumnAndRow($column, $row);
393
394	for ($column = 0; $column < $max; $column++) {
395	$worksheet->setCellValueByColumnAndRow($column, $row, 'value ' . $column);
396	}
397
398	// After
399	$cell = $worksheet->getCellByColumnAndRow($column + 1, $row);
400
401	for ($column = 1; $column <= $max; $column++) {
402	$worksheet->setCellValueByColumnAndRow($column, $row, 'value ' . $column);
403	}
404	```
405
406	All the following methods are affected:
407
408	- `PHPExcel_Worksheet::cellExistsByColumnAndRow()`
409	- `PHPExcel_Worksheet::freezePaneByColumnAndRow()`
410	- `PHPExcel_Worksheet::getCellByColumnAndRow()`
411	- `PHPExcel_Worksheet::getColumnDimensionByColumn()`
412	- `PHPExcel_Worksheet::getCommentByColumnAndRow()`
413	- `PHPExcel_Worksheet::getStyleByColumnAndRow()`
414	- `PHPExcel_Worksheet::insertNewColumnBeforeByIndex()`
415	- `PHPExcel_Worksheet::mergeCellsByColumnAndRow()`
416	- `PHPExcel_Worksheet::protectCellsByColumnAndRow()`
417	- `PHPExcel_Worksheet::removeColumnByIndex()`
418	- `PHPExcel_Worksheet::setAutoFilterByColumnAndRow()`
419	- `PHPExcel_Worksheet::setBreakByColumnAndRow()`
420	- `PHPExcel_Worksheet::setCellValueByColumnAndRow()`
421	- `PHPExcel_Worksheet::setCellValueExplicitByColumnAndRow()`
422	- `PHPExcel_Worksheet::setSelectedCellByColumnAndRow()`
423	- `PHPExcel_Worksheet::stringFromColumnIndex()`
424	- `PHPExcel_Worksheet::unmergeCellsByColumnAndRow()`
425	- `PHPExcel_Worksheet::unprotectCellsByColumnAndRow()`
426	- `PHPExcel_Worksheet_PageSetup::addPrintAreaByColumnAndRow()`
427	- `PHPExcel_Worksheet_PageSetup::setPrintAreaByColumnAndRow()`
428
429	### Removed default values
430
431	Default values for many methods were removed when it did not make sense. Typically,
432	setter methods should not have default values. For a complete list of methods and
433	their original default values, see [](https://github.com/PHPOffice/PhpSpreadsheet/commit/033a4bdad56340795a5bf7ec3c8a2fde005cda24that commit](https://github.com/PHPOffice/PhpSpreadsheet/commit/033a4bdad56340795a5bf7ec3c8a2fde005cda24](https://github.com/PHPOffice/PhpSpreadsheet/commit/033a4bdad56340795a5bf7ec3c8a2fde005cda24).
434