UPGRADE-4.x.md
Laravel-Excel 4.0 requires PHP 8.3 or higher, and Laravel 12 or higher. If you are using an older version of PHP or Laravel, you will need to upgrade those first before upgrading to Laravel-Excel 4.0.
The underlying phpoffice/phpspreadsheet dependency has been upgraded from ^1.30 to ^5.3.
Code that only uses Laravel-Excel's own API (exports, imports, concerns) is largely unaffected, but anywhere you interact
with PhpSpreadsheet objects directly you should review your code against the PhpSpreadsheet breaking changes. Common places
where this happens:
WithEvents (e.g. styling a sheet through $event->sheet->getDelegate() in AfterSheet).WithCharts and WithDrawings concerns, which return PhpSpreadsheet chart and drawing objects.WithCustomValueBinder) and anything extending DefaultValueBinder.NumberFormat, Style, or Coordinate in your exports and imports.See the PhpSpreadsheet changelog and release notes for the 2.0, 3.0, 4.0 and 5.0 breaking changes.
Native PHP types were added across the entire code base, including public methods and interfaces. If you are implementing any of the interfaces or overriding any methods, you will need to update your code to match the new method signatures to include native types:
class MyExport implements FromArray
{
public function array(): array
{
}
}
Because return types are now enforced natively, some signatures are stricter than the 3.1 docblocks suggested:
Exportable::store() returns bool|PendingDispatch|PendingBatch and Exportable::queue() returns PendingDispatch|PendingBatch.Importable::import() returns Importer|PendingDispatch|PendingBatch and Importable::queue() returns PendingDispatch|PendingBatch
(it no longer advertises returning the importable instance itself).To keep laravel/scout an optional dependency, FromQuery no longer supports returning a Scout Builder instance.
Use the new FromScout export interface instead.
ShouldBatch)Queued exports and chunked queued imports can now implement the Maatwebsite\Excel\Concerns\ShouldBatch marker interface
to be dispatched as a job batch instead of a chain. When an export or
import implements ShouldBatch, methods such as Excel::store(), Excel::queue(), Exportable::queue() and
Importable::queue() return an Illuminate\Bus\PendingBatch instead of a PendingDispatch — update any code that
type-hints these return values.
Imports can specify their queue and connection with Laravel's native #[Queue] and #[Connection] attributes
(Laravel 13), in addition to the existing queue and connection properties.
The published configuration file (config/excel.php) has no key changes compared to 3.1 — there is no need to
republish or migrate your configuration.
Two new marker interfaces have been introduced: Maatwebsite\Excel\Concerns\Export and Maatwebsite\Excel\Concerns\Import.
All export-related concerns (e.g. FromArray, FromCollection, FromQuery) now extend Export, and all import-related
concerns (e.g. ToModel, ToArray, ToCollection, OnEachRow) now extend Import. Because your export and import classes already
implement those concerns, they automatically satisfy the new interfaces — no changes are required in most cases.
You can now use Export and Import as type hints wherever you previously used object to represent an export or import:
use Maatwebsite\Excel\Concerns\Export;
public function handle(Export $export): void { ... }
The sheets() method docblock return type has been narrowed from array<int|string, object> to array<int|string, Export|Import>.
Sheets returned from this method should implement at least one export or import concern interface, which is almost certainly
already the case.
It is also necessary for your import or export class to implement Export or Import accordingly if you use this concern.
Event::getConcernable() now returns Export|Import|null instead of object. If you call this method and rely on the
object return type in a type-strict context, update your code accordingly.
The ext-json requirement has been dropped (JSON support is bundled with PHP 8). No action is required.