# Laravel Excel Use this skill when a Laravel task involves spreadsheet exports, imports, queued spreadsheet processing, CSV files, or package maintenance for `maatwebsite/excel`. ## Read First Use `search-docs` when it is available for Laravel framework integration details. For package-specific behavior in this repository, inspect: - `src/Excel.php` - `src/Exporter.php` - `src/Importer.php` - `src/Concerns/` - `src/Fakes/ExcelFake.php` - `config/excel.php` - `tests/Concerns/` - `tests/ExcelFakeTest.php` - `../../examples/exports-imports.md` - `../../references/package.md` If the user asks for complete coverage, "all features", package docs, package skills, or a missing-feature audit, read `../../references/package.md` first and use it as the checklist. ## Working Rules - Keep controllers thin. Put spreadsheet behavior in dedicated export/import classes. - Use package concerns to declare behavior instead of custom imperative spreadsheet code. - Before claiming feature completeness, compare the output against `../../references/package.md`. - Use `Exportable` on export classes when the export should call `download()`, `store()`, `queue()`, or `raw()` directly. - Use `Importable` on import classes when the import should call `import()`, `queue()`, `toArray()`, or `toCollection()` directly. - Prefer `FromQuery` for large exports so the package can chunk records efficiently. - Prefer `WithChunkReading` plus `WithBatchInserts` for large `ToModel` imports. - Add Laravel's `Illuminate\Contracts\Queue\ShouldQueue` to exports/imports that may exceed request time limits. - Use `WithMultipleSheets` for workbooks with multiple worksheets, and keep each sheet as its own export/import object. - Use `WithHeadingRow` when import files have user-facing headers; validate using heading keys instead of numeric indexes. - Use `WithValidation`, `SkipsOnFailure`, `SkipsFailures`, `SkipsOnError`, and `SkipsErrors` deliberately when importing untrusted user files. - Use `WithCustomCsvSettings` for delimiter, enclosure, input encoding, or BOM-sensitive CSV work. - Use PhpSpreadsheet concerns and events only when package concerns do not cover the required formatting or worksheet behavior. - Do not load large spreadsheets fully into memory unless the task explicitly needs complete workbook inspection. ## Feature Coverage Checklist Use `../../references/package.md` for the complete matrix. It covers: - Facade APIs, object traits, contracts, file type constants, and extension detection. - Export sources, export formatting, events, styles, formulas, charts, drawings, properties, multiple sheets, conditional sheets, and CSV settings. - Import targets, heading rows, grouped headings, mapped cells, read filters, row/column limits, formulas, formatting, empty rows, unknown sheets, row numbers, and chunk offsets. - Validation, failures, errors, batch inserts, upserts, duplicate handling, relation persistence, queues, batches, and queue-without-chain behavior. - Console generators, published stubs/config, collection/query macros, cache, transactions, temporary files, remote temp disks, value binders, cell middleware, fakes, and package test locations. ## Common API Exports: - `Excel::download($export, 'file.xlsx')` - `Excel::store($export, 'exports/file.xlsx', 'disk')` - `Excel::queue($export, 'exports/file.xlsx', 'disk')` - `Excel::raw($export, Excel::XLSX)` Imports: - `Excel::import($import, $filePath, $disk)` - `Excel::queueImport($import, $filePath, $disk)` - `Excel::toArray($import, $filePath, $disk)` - `Excel::toCollection($import, $filePath, $disk)` Writer and reader types are usually detected from the file extension. Pass explicit types such as `Excel::XLSX` or `Excel::CSV` when the extension is absent or ambiguous. ## Export Pattern Start with the smallest concern set that matches the source: - `FromCollection` for an existing collection. - `FromArray` for simple arrays. - `FromGenerator` or `FromIterator` for streamed in-memory rows. - `FromQuery` for Eloquent or query builder datasets. - `FromView` when a Blade table is the clearest representation. Add output concerns only when needed: - `WithHeadings` for header rows. - `WithMapping` for row transformation. - `WithColumnFormatting` for Excel number/date formats. - `ShouldAutoSize` or `WithColumnWidths` for layout. - `WithStyles`, `WithDefaultStyles`, `WithBackgroundColor`, or `WithEvents` for workbook styling. ## Import Pattern Choose the import target deliberately: - `ToModel` to persist rows as Eloquent models. - `ToCollection` for application-level processing. - `ToArray` for lightweight read-only extraction. - `OnEachRow` for row-by-row custom handling. For production user uploads, include validation and failure behavior instead of assuming perfect files. Use chunk reading for large files and avoid cross-row state that cannot survive queued chunk jobs. ## Queues And Batches - If an export/import implements `ShouldQueue`, `store()` and `import()` may dispatch queued work. - Use `queue()` or `queueImport()` when queueing should be explicit at the call site. - Use `ShouldBatch` when the export/import should return a Laravel pending batch. - Use `ShouldQueueWithoutChain` only when queued import chunks should not be chained. - Keep queued export/import classes serializable. Avoid closures, open file handles, or non-serializable service instances on properties. ## Testing - Use `Excel::fake()` when testing that a controller, command, job, or service requested the correct spreadsheet operation. - Assert intent with `assertDownloaded()`, `assertStored()`, `assertQueued()`, `assertImported()`, and `assertExportedInRaw()`. - Use callback assertions to verify the export/import object class and constructor state. - Generate and read real spreadsheet files only when testing cell values, multiple sheets, formatting, formulas, or PhpSpreadsheet compatibility. - In this package repository, follow existing PHPUnit tests under `tests/Concerns/`, `tests/ExcelFakeTest.php`, and `tests/Queued*Test.php`. ## Maintenance Notes - Preserve Laravel auto-discovery entries in `composer.json` for the service provider and `Excel` facade alias. - Keep config changes in `config/excel.php` backward compatible unless the task explicitly targets a breaking release. - When changing a concern, update or add tests near the matching `tests/Concerns/*Test.php` file. - When changing fakes, update `tests/ExcelFakeTest.php`. - When changing queue behavior, update the matching queued import/export tests.

Laravel Excel

Use this skill when a Laravel task involves spreadsheet exports, imports, queued spreadsheet processing, CSV files, or package maintenance for maatwebsite/excel.

Read First

Use search-docs when it is available for Laravel framework integration details. For package-specific behavior in this repository, inspect:

src/Excel.php
src/Exporter.php
src/Importer.php
src/Concerns/
src/Fakes/ExcelFake.php
config/excel.php
tests/Concerns/
tests/ExcelFakeTest.php
../../examples/exports-imports.md
../../references/package.md

If the user asks for complete coverage, "all features", package docs, package skills, or a missing-feature audit, read ../../references/package.md first and use it as the checklist.

Working Rules

Keep controllers thin. Put spreadsheet behavior in dedicated export/import classes.
Use package concerns to declare behavior instead of custom imperative spreadsheet code.
Before claiming feature completeness, compare the output against ../../references/package.md.
Use Exportable on export classes when the export should call download(), store(), queue(), or raw() directly.
Use Importable on import classes when the import should call import(), queue(), toArray(), or toCollection() directly.
Prefer FromQuery for large exports so the package can chunk records efficiently.
Prefer WithChunkReading plus WithBatchInserts for large ToModel imports.
Add Laravel's Illuminate\Contracts\Queue\ShouldQueue to exports/imports that may exceed request time limits.
Use WithMultipleSheets for workbooks with multiple worksheets, and keep each sheet as its own export/import object.
Use WithHeadingRow when import files have user-facing headers; validate using heading keys instead of numeric indexes.
Use WithValidation, SkipsOnFailure, SkipsFailures, SkipsOnError, and SkipsErrors deliberately when importing untrusted user files.
Use WithCustomCsvSettings for delimiter, enclosure, input encoding, or BOM-sensitive CSV work.
Use PhpSpreadsheet concerns and events only when package concerns do not cover the required formatting or worksheet behavior.
Do not load large spreadsheets fully into memory unless the task explicitly needs complete workbook inspection.

Feature Coverage Checklist

Use ../../references/package.md for the complete matrix. It covers:

Facade APIs, object traits, contracts, file type constants, and extension detection.
Export sources, export formatting, events, styles, formulas, charts, drawings, properties, multiple sheets, conditional sheets, and CSV settings.
Import targets, heading rows, grouped headings, mapped cells, read filters, row/column limits, formulas, formatting, empty rows, unknown sheets, row numbers, and chunk offsets.
Validation, failures, errors, batch inserts, upserts, duplicate handling, relation persistence, queues, batches, and queue-without-chain behavior.
Console generators, published stubs/config, collection/query macros, cache, transactions, temporary files, remote temp disks, value binders, cell middleware, fakes, and package test locations.

Common API

Exports:

Excel::download($export, 'file.xlsx')
Excel::store($export, 'exports/file.xlsx', 'disk')
Excel::queue($export, 'exports/file.xlsx', 'disk')
Excel::raw($export, Excel::XLSX)

Imports:

Excel::import($import, $filePath, $disk)
Excel::queueImport($import, $filePath, $disk)
Excel::toArray($import, $filePath, $disk)
Excel::toCollection($import, $filePath, $disk)

Writer and reader types are usually detected from the file extension. Pass explicit types such as Excel::XLSX or Excel::CSV when the extension is absent or ambiguous.

Export Pattern

Start with the smallest concern set that matches the source:

FromCollection for an existing collection.
FromArray for simple arrays.
FromGenerator or FromIterator for streamed in-memory rows.
FromQuery for Eloquent or query builder datasets.
FromView when a Blade table is the clearest representation.

Add output concerns only when needed:

WithHeadings for header rows.
WithMapping for row transformation.
WithColumnFormatting for Excel number/date formats.
ShouldAutoSize or WithColumnWidths for layout.
WithStyles, WithDefaultStyles, WithBackgroundColor, or WithEvents for workbook styling.

Import Pattern

Choose the import target deliberately:

ToModel to persist rows as Eloquent models.
ToCollection for application-level processing.
ToArray for lightweight read-only extraction.
OnEachRow for row-by-row custom handling.

For production user uploads, include validation and failure behavior instead of assuming perfect files. Use chunk reading for large files and avoid cross-row state that cannot survive queued chunk jobs.

Queues And Batches

If an export/import implements ShouldQueue, store() and import() may dispatch queued work.
Use queue() or queueImport() when queueing should be explicit at the call site.
Use ShouldBatch when the export/import should return a Laravel pending batch.
Use ShouldQueueWithoutChain only when queued import chunks should not be chained.
Keep queued export/import classes serializable. Avoid closures, open file handles, or non-serializable service instances on properties.

Testing

Use Excel::fake() when testing that a controller, command, job, or service requested the correct spreadsheet operation.
Assert intent with assertDownloaded(), assertStored(), assertQueued(), assertImported(), and assertExportedInRaw().
Use callback assertions to verify the export/import object class and constructor state.
Generate and read real spreadsheet files only when testing cell values, multiple sheets, formatting, formulas, or PhpSpreadsheet compatibility.
In this package repository, follow existing PHPUnit tests under tests/Concerns/, tests/ExcelFakeTest.php, and tests/Queued*Test.php.

Maintenance Notes

Preserve Laravel auto-discovery entries in composer.json for the service provider and Excel facade alias.
Keep config changes in config/excel.php backward compatible unless the task explicitly targets a breaking release.
When changing a concern, update or add tests near the matching tests/Concerns/*Test.php file.
When changing fakes, update tests/ExcelFakeTest.php.
When changing queue behavior, update the matching queued import/export tests.