UPGRADE FROM 3.1 to 4.0
=======================

## Minimum dependency versions

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.

## PhpSpreadsheet 5

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:

- Event listeners registered via `WithEvents` (e.g. styling a sheet through `$event->sheet->getDelegate()` in `AfterSheet`).
- The `WithCharts` and `WithDrawings` concerns, which return PhpSpreadsheet chart and drawing objects.
- Custom value binders (`WithCustomValueBinder`) and anything extending `DefaultValueBinder`.
- Direct use of PhpSpreadsheet classes such as `NumberFormat`, `Style`, or `Coordinate` in your exports and imports.

See the PhpSpreadsheet [changelog](https://github.com/PHPOffice/PhpSpreadsheet/blob/master/CHANGELOG.md) and
[release notes](https://github.com/PHPOffice/PhpSpreadsheet/releases) for the 2.0, 3.0, 4.0 and 5.0 breaking changes.

## Fully typed code base

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:

```php
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).

## FromScout

To keep laravel/scout an optional dependency, `FromQuery` no longer supports returning a Scout `Builder` instance.
Use the new `FromScout` export interface instead.

## Job batching (`ShouldBatch`)

Queued exports and chunked queued imports can now implement the `Maatwebsite\Excel\Concerns\ShouldBatch` marker interface
to be dispatched as a [job batch](https://laravel.com/docs/queues#job-batching) 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.

## Queue attributes

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.

## Configuration

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.

## Removed requirements

The `ext-json` requirement has been dropped (JSON support is bundled with PHP 8). No action is required.