Laravel Excel

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.