Filament Xlsx Import Laravel Package

Product Decisions This Supports

• Build vs. buy for spreadsheet ingestion. This package covers a narrow, well-understood slice — an admin-panel "Import from XLSX/CSV" action inside Filament — so the buy decision is easy to justify against even a few days of engineering time. It is a UI/integration layer over openspout, not a bespoke parsing engine, so you are buying wiring and validation ergonomics, not proprietary technology.
• Which import surfaces ship in v1 of an admin tool. The sheet('X'), headerOffset(), and acceptCsv() toggles map directly to product requirements you would otherwise argue about in refinement: "only import from the 'Data' tab", "our exports have two title rows before the header", "customers export as CSV from Excel and we don't want to support .xls". Each is a config flag rather than a story.
• Scope boundary for the roadmap. The documented memory behaviour — data rows streamed once at import start, but core's ImportDispatcher constructs every chunk's job in that initial request, so request memory grows with row count — is a product constraint, not just an implementation note. It tells you this package is right for bounded, human-scale uploads (thousands to low tens of thousands of rows) and that "import a 500k-row customer list" is a separate initiative requiring queueing, chunked upload, or an out-of-band job pipeline.
• Support matrix as a commitment. Tested on PHP 8.2–8.5, Laravel 12/13, Filament 4/5, with the lowest supported openspout (4.23) verified, plus a fresh composer require on clean apps and a headless-Chrome UI test. That is enough to slot into a framework-upgrade plan without budgeting a migration spike, and it de-risks the "we'll upgrade Laravel next quarter" conversation.
• Error and failure UX. The sheet('X') fix means a misconfigured or unexpected workbook produces a message an admin can act on ("The workbook has no sheet called "X"") rather than a dead-end "could not be read as a spreadsheet". The acceptCsv(false) fix means the file picker stops silently rejecting .xls before the guidance about saving as .xlsx can be shown — i.e. users get told what to do instead of being blocked without explanation. Both reduce support tickets, which is a measurable PM concern.
• Use cases it directly enables: bulk onboarding of records from an existing system, periodic price/inventory/catalogue refreshes by ops staff, data migration into a new tenant, and letting a non-technical admin correct data in Excel and push it back — all without a bespoke upload endpoint per entity.

When to Consider This Package

Adopt it when:

• You are already on Filament 4 or 5 with Laravel 12/13 and PHP 8.2+. The package is explicitly a Filament integration; outside that stack it has no value.
• Your imports are operator-driven and bounded — a person uploading a file in an admin panel, expecting a result within a request. Given the documented memory profile, treat this as the right tool for files up to a size you are comfortable materialising jobs for in one request; validate against your own data before committing to a number.
• You need multiple file formats (XLSX, optionally CSV) with per-import control over sheet selection, header offset, and CSV acceptance — the config surface is small and each option corresponds to a real customer-data shape.
• You want column mapping without writing a parser. Note the mapping step re-reads the sheet list and header rows (not the data), so it is cheap relative to the import itself — but it is still a read, so keep it in mind for very large sheets.
• You are willing to pin and upgrade deliberately — patch releases are cheap (composer update amjadiqbal/filament-xlsx-import, no API changes in 1.0.1), but the package is at 1.0.x with a maintainer-driven test matrix rather than a large ecosystem.

Look elsewhere (or build) when:

• You need very large or unbounded files. The request-memory growth with row count is a hard characteristic of the current design; you would want a queue-first or signed-upload pipeline instead.
• You need fine-grained validation, transformation, or mapping logic per column type beyond what your importer callback handles — at that point you are writing the real logic anyway and should evaluate a lower-level library (e.g. openspout or Laravel Excel directly).
• You need non-Filament UI, an API-only ingestion path, or an import that runs outside a web request lifecycle.
• You need strict SLA-backed support or a formal security review cadence — single-maintainer packages are a supply-chain consideration; check licence, release cadence, and whether the dependency tree (openspout) fits your audit posture.
• You require legacy .xls input as a first-class format rather than an error message telling users to re-save as .xlsx.

How to Pitch It (Stakeholders)

For executives: We need bulk data entry in the admin panel for [onboarding / catalogue refresh / migrations]. This is an off-the-shelf Laravel/Filament package that covers the whole "upload a spreadsheet, pick a sheet, map columns, import" flow, tested across our current PHP, Laravel, and Filament versions. It replaces a custom build estimated at [X days] with a dependency we can adopt this sprint. The 1.0.1 patch is a stabilisation release — better error messages when a file is missing an expected sheet, a fix so users who upload .xls are told to save as .xlsx instead of being silently blocked, and clearer documentation of how large files are handled. No API changes; upgrade is a one-line Composer update.

For engineering: It is a thin, honest wrapper over openspout with Filament form/action wiring. Version 1.0.1 is a code-review-driven patch: no API changes, composer update only. Two behavioural fixes (sheet-not-found message; acceptCsv(false) no longer pre-rejecting .xls) and a README correction. The important engineering fact, now documented rather than discovered in production: data rows are streamed once at import start, but core's ImportDispatcher builds every chunk's job in that first request, so request memory scales with row count — same as the CSV path. Column mapping re-reads only the sheet list and header rows. headerOffset() counts empty rows, so headerOffset(2) reads row 3. Verified on PHP 8.2–8.5 × Laravel 12/13 × Filament 4/5, against the lowest supported openspout (4.23), with a fresh Composer install and a headless-Chrome UI test. Practical implication: size-gate uploads or move large imports to a queued upload path before we promise big-file support.

Recommendation: Adopt for the admin import workflows in scope, pin the version, and file the large-file/queueing work as a separate backlog item rather than treating it as a gap in this package.