Skip to main content
This guide covers breaking changes between major versions and provides instructions for upgrading your code.

​
Version 5.0 (2025-08-10)

​
Breaking Changes

External Images: Images will be loaded from external sources (e.g., http://example.com/img.png) only if the reader is explicitly set to allow it via $reader->setAllowExternalImages(true). This feature is not widely used, so most users won’t be affected.

​
Removed Deprecated Items

The following items deprecated in Release 4 have been removed:
  • Theme public constants: COLOR_SCHEME_2013_PLUS_NAME (use COLOR_SCHEME_2013_2022_NAME) and COLOR_SCHEME_2013_PLUS (use COLOR_SCHEME_2013_2022)

​
Reader Property Changes

Some properties have been moved from Base Reader to Html Reader. See PR #4551.

​
DefaultValueBinder Behavior

DefaultValueBinder will now treat integers with more than 15 digits as strings to prevent precision loss. Issue #4522

​
Key Fixes

  • Additional floating-point precision improvements Issue #1324
  • Header/Footer images path expansion Issue #484
  • Create uninitialized cells when used in calculations Issue #4558
  • Fixed Shared/Date::isDateTime to handle cells with array results Issue #4557

​
Version 4.0 (2025-02-08)

​
Breaking Changes

​
Data Validations Storage

Data Validations are now stored by worksheet, not by cell. The index can be one or more cells or cell ranges. Issue #797

​
Conditional Formatting Changes

Conditional Formatting now includes a Priority property and handles overlapping ranges better. Issue #4312

​
CSV Reader Mac Line Endings

CSV Reader will no longer auto-detect Mac line endings by default. Enable via setTestAutoDetect(true). This feature will not be available in PHP 9+.

​
Html Writer Boolean Output

Html Writer now uses “better boolean” logic by default. Booleans will be output as TRUE/FALSE instead of 1/null-string. Restore old behavior with setBetterBoolean(false).

​
Xlsx Writer Force Full Calc

Xlsx Writer now defaults to false for forceFullCalc. This affects writes with preCalculateFormulas set to false. Restore old behavior with setForceFullCalc(null).

​
Removed Items

The following items deprecated in Release 3 have been removed:
  • Worksheet::getStyles - no replacement
  • Drawing::setIsUrl - no replacement
  • Settings::setLibXmlLoaderOptions() and Settings::getLibXmlLoaderOptions() - no replacement
  • Worksheet::getHashCode - no replacement
  • IReader::SKIP_EMPTY_CELLS - use IGNORE_EMPTY_CELLS instead
  • Worksheet::getProtectedCells - use getProtectedCellRanges instead
  • Writer/Html::isMpdf property - use instanceof Mpdf instead

​
Added Features

  • PDF Charts and Drawings: Charts and drawings are now supported in PDF output Discussion #4129
  • Spreadsheet Serialization: Spreadsheets can now be serialized Discussion #4324

​
Version 3.0 (2024-09-29)

​
Dynamic Arrays Support

Support for Excel dynamic arrays has been added as an opt-in feature. Full support is available for Xlsx format. It’s emulated as Ctrl-Shift-Enter arrays for Ods, Excel2003, and Gnumeric. No support for Xls or Slk formats.

​
Breaking Changes

​
Xlsx Reader Default Datatype

Default datatype when none is specified in XML changed from string to numeric, matching Excel’s behavior. Most users won’t be affected as DefaultValueBinder and AdvancedValueBinder correct the mis-identification.

​
Currency and Accounting Wizards

Currency and Accounting Wizards now match Excel behavior. A new CurrencyBase Wizard has been added for non-Excel formats. Issue #4125

​
Image Validation

Images will not be added to spreadsheet if they cannot be validated as images.

​
Removed Items

The following items deprecated in Release 2 have been removed:
  • Writer\Xls\Style\ColorMap - no longer needed
  • Reader\Xml::trySimpleXMLLoadString - should not have been public
  • Calculation\Calculation::_translateFormulaToLocale - use translateFormulaToLocale (without underscore)
  • Calculation\Calculation::_translateFormulaToEnglish - use translateFormulaToEnglish (without underscore)

​
Version 2.0 Key Features

​
Minor Breaking Change (2.2.0)

Writing cell comments to HTML will now sanitize all HTML tags within the comment. Tags will be rendered as plaintext with no effects. Use the Font property of TextRuns for styling, as with Xlsx.

​
Key Additions

​
Important Changes

​
Range Preservation

Xlsx Reader now tries to preserve union ranges as they were read in, instead of breaking them into separate ranges. PR #4042

​
Date Calculations

Xlsx/Xls spreadsheet calculations and date formatting now use the base date of the spreadsheet, even when spreadsheets with different base dates are simultaneously open. Issue #1036

​
PHP Version Support

For maintained branches, support for PHP versions will only be maintained for six months beyond the end of life of that PHP version.

​
Current Requirements

  • Minimum PHP Version: 8.1
  • Support Period: Until June 30, 2026
See the composer.json for other requirements.

​
Common Upgrade Tasks

​
Updating External Image Loading (5.0+)

If you need to load external images: 
use PhpOffice\PhpSpreadsheet\IOFactory;

$reader = IOFactory::createReader('Xlsx');
$reader->setAllowExternalImages(true);
$spreadsheet = $reader->load('file.xlsx');

​
Updating Boolean Output in HTML (4.0+)

To restore old boolean output behavior: 
use PhpOffice\PhpSpreadsheet\Writer\Html;

$writer = new Html($spreadsheet);
$writer->setBetterBoolean(false);
$writer->save('output.html');

​
Updating CSV Mac Line Ending Detection (4.0+)

To enable Mac line ending auto-detection: 
use PhpOffice\PhpSpreadsheet\Reader\Csv;

$reader = new Csv();
$reader->setTestAutoDetect(true);
$spreadsheet = $reader->load('file.csv');

​
Migrating to Dynamic Arrays (3.0+)

Dynamic arrays are opt-in. To enable: 
use PhpOffice\PhpSpreadsheet\Calculation\Calculation;

$calculation = Calculation::getInstance($spreadsheet);
$calculation->setDynamicArrays(true);

​
Replacing Deprecated Methods

Replace deprecated methods before upgrading: 
// Data Validations (4.0)
// Before
$validation = $worksheet->getCell('A1')->getDataValidation();

// After
$validations = $worksheet->getDataValidations();
$validation = $validations['A1'] ?? null;

// Protected Cells (4.0)
// Before
$protectedCells = $worksheet->getProtectedCells();

// After
$protectedCells = $worksheet->getProtectedCellRanges();

// Skip Empty Cells (4.0)
// Before
$reader->setReadDataOnly(true);
$reader->setReadEmptyCells(IReader::SKIP_EMPTY_CELLS);

// After
$reader->setReadDataOnly(true);
$reader->setReadEmptyCells(IReader::IGNORE_EMPTY_CELLS);

​
Testing Your Upgrade

After upgrading, thoroughly test your application, especially:
  • External image loading (if used)
  • Boolean value rendering in HTML output
  • CSV file reading with Mac line endings
  • Data validation and conditional formatting logic
  • Large integer handling (15+ digits)
  1. Run your test suite to catch any immediate breaking changes
  2. Test file reading with various formats (Xlsx, Csv, Ods, etc.)
  3. Verify calculations especially if using dynamic arrays
  4. Check rendered output for HTML and PDF exports
  5. Validate data integrity for cells with large numbers or specific datatypes

​
Getting Help

If you encounter issues during migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us