Technical Evaluation

Architecture fit

amjadiqbal/filament-xlsx-import is a thin Filament plugin that extends Filament's native importer with XLSX support (and optional CSV) via openspout. It does not introduce a parallel import pipeline — it plugs into core's ImportDispatcher/chunk-job model, which is the right shape for a Filament-first stack.
v1.0.1 is a patch from a code review: no API surface changes, no deprecations, no config or schema changes. Adoption cost is a composer update.
Scope is deliberately narrow (file→rows, header handling, sheet selection, column mapping). That narrowness is a strength for integration risk and a constraint if we later need transforms, validation beyond Filament's, or non-Filament entry points.

Integration feasibility

Supported matrix is broad and credibly tested: PHP 8.2–8.5 × Laravel 12/13 × Filament 4/5, plus the lowest allowed openspout (4.23), plus a fresh composer require on clean Laravel 12 + Filament 4 and Laravel 13 + Filament 5 apps with a headless-Chrome UI test. That is a stronger signal than a typical 1.0.x patch.
45 Pest tests plus Pint and PHPStan level 5. Level 5 is moderate, not maximal — acceptable for a small plugin, but it means type-safety guarantees are bounded.
No migration steps, no breaking changes, no published config changes indicated.

Technical risk

Primary risk is request memory growth: the README now states data rows are streamed once at import start, but core's ImportDispatcher constructs every chunk's job in that request (same as CSV). Streaming therefore does not bound peak memory — memory scales with row count, not chunk size. For large workbooks this is an operational ceiling, not a bug, but it must be planned for.
Coupling to Filament core internals (ImportDispatcher job construction) is the main upgrade hazard: a Filament major that changes dispatch semantics could change memory behavior or break the plugin without an API change on the plugin's side.
.xls handling and missing-sheet messaging were incorrect in 1.0.0; both are user-facing failure modes now fixed, which reduces confusing support traffic.
headerOffset() counts empty rows (headerOffset(2) reads row 3) — documented, but a likely source of misconfiguration in real spreadsheets with blank leading rows.

Key questions

What is the realistic maximum rows per import in our use cases, and what memory_limit and chunk size do we need to hold that?
Are imports dispatched to a queue worker, and is the initial dispatch request executed in a web request or a job context? (Determines whether memory pressure hits PHP-FPM or a worker.)
Do we rely on .xls uploads at all, or is XLSX-only acceptable? Do we need acceptCsv(false) behavior?
Which Filament major will we standardize on, and do we have a test that pins the plugin against it before upgrading?
Is static analysis at level 5 sufficient for our standards, or do we need to gate on a higher level ourselves?

Integration Approach

Stack fit

Fits any Laravel 12/13 + Filament 4/5 admin panel already using Filament's importer. Value is concentrated in XLSX support and correct spreadsheet semantics rather than new workflow capability.
Low footprint: one composer dependency (openspout) plus the plugin; no new services, no external storage assumptions stated.

Migration path

From a CSV-only Filament importer: additive — enable XLSX, keep CSV path, adopt the plugin's CSV example file as the reference template.
From the plugin's own v1.0.0: composer update amjadiqbal/filament-xlsx-import, no code changes. Re-run our import smoke test and confirm the two fixed behaviors (missing sheet message, .xls rejection copy).

Compatibility

Pin to ^1.0 and record the tested matrix in our dependency policy. Treat Filament major upgrades as requiring an explicit re-test of this plugin, with the headless UI import test as the gate.
Verify our installed openspout resolves at or above 4.23; the plugin is tested at that floor.

Sequencing

Update the package in a branch; run the existing suite.
Exercise both fixed paths: import against a workbook missing the named sheet; upload .xls with acceptCsv(false).
Run a production-sized workbook through a staging import while measuring peak memory of the dispatch request; record rows-per-MB to derive a safe row ceiling.
Set operational guardrails (max upload size, row cap, memory limit, chunk size) based on step 3.
Roll out to one importer, then the rest; keep CSV path unchanged until XLSX is proven.

Maintenance

Single-maintainer package; the v1.0.1 release is itself the output of a code review, which is a positive maintenance signal. Budget for periodic review of Filament core changes that affect dispatch behavior.
Dependency surface is small (Filament core + openspout), which keeps upgrade triage cheap.

Support

The README change is the highest-value operational item: documented memory behavior, headerOffset() semantics, and template provenance remove the three most likely "why did it do that" tickets.
Improved error text for a missing sheet and correct .xls rejection copy reduce misdiagnosed "file is corrupt" reports.

Scaling

Throughput scales with queue workers and chunk size; peak memory scales with total row count in the dispatch request. Plan for a documented row ceiling per import, enforce an upload size limit, and consider pre-splitting large workbooks upstream.
Column mapping cost is bounded (re-reads sheet list and header rows only), so mapping preview stays cheap regardless of file size.

Failure modes

Memory exhaustion on large workbooks at dispatch time (the dominant risk); symptom is a 500/timeout before any chunk job runs.
Header row misalignment from blank rows when headerOffset is misused — produces shifted or lost columns rather than an error.
Missing/renamed sheet names — now fails with a clear message, but still a run-time failure, not a validation-time one.
Filament major upgrade changing ImportDispatcher internals; would surface as duplicate, missing, or memory-heavy job dispatch.
openspout resolved below the tested floor, or a transitive bump outside the tested matrix.

Ramp-up

Low. The API mirrors Filament's importer concepts (sheet(), acceptCsv(), headerOffset()), so a developer familiar with Filament imports is productive in under a day.
Onboarding should include the README's memory section and the header-offset example; both are the most common sources of incorrect first implementations.