Filament Import Wizard Laravel Package

Technical Evaluation

Architecture fit

• The package is shaped as a Filament Action (ImportWizardAction) plus a Livewire wizard component, queued chunk jobs, a published config, and published migrations. It fits a Filament-4 admin panel cleanly and requires no changes to our domain models beyond optional getImportRules() / getImportFieldLabel() methods.
• Import state is owned by the package: a 4-step Livewire wizard (upload → map → review → import) with persisted import records, progress polling, and downloadable error CSVs. That means the package owns a table and a UI surface inside our admin, not just a service class — a real but bounded coupling.
• Processing model is chunked queue jobs (default 1000 rows) with two distinct write paths: per-record save() (Eloquent events, observers, timestamps fire) and bulk upsert() (events do not fire). This asymmetry is the single most important architectural detail for us.
• Validation is derived from live DB schema introspection (Schema::getColumnListing), with an override hook. Elegant, but it makes import behavior a function of current migrations rather than an explicit contract.
• Relationship handling is BelongsTo-only, with find-or-create semantics and auto-increment ID heuristics. No BelongsToMany, MorphTo, or pivot support documented.

Integration feasibility

• Low ceremony: composer require, optional config publish, required migration publish, filament:assets rebuild. A developer can produce a working import on one model in under a day.
• Hard gate: PHP 8.2+, Laravel 10+, Filament 4.x/5.x. If we are on Filament 3 or Laravel 9, this is a non-starter without an upgrade we would not do for an import feature.
• The standalone Livewire mode (@livewire('filament-import-wizard', ...)) gives optionality to expose imports outside the admin panel later, which is a genuine plus for customer-facing bulk upload.
• Verification burden is on us: README claims multi-tenancy across queue boundaries, Spatie Translatable detection, and 100K+ row handling, but there is no test suite, benchmark, or driver-compatibility matrix in the published material.

Technical risk

• Adoption risk dominates. 12 stars, 0 dependents, single maintainer, rapid 1.0.0 → 1.1.1 churn, and an aggregate score of ~18/100. The code may be good; the ecosystem signal says "assume you may own this fork."
• Behavioral inconsistency (highest functional risk). Upsert mode updates rows without firing model events, observers, or boot() hooks. Any audit log, webhook, search-index sync, or notification observer we rely on will silently not run for updated records. The documented "fallback to chunked inserts on upsert failure" compounds this: the same batch can take two different code paths.
• Master-data pollution. Relation linking auto-creates related records from free-text CSV values ("Electronics" vs "electronics " vs "Electronic"). No fuzzy match, normalization, or dry-run report of would-be-created relations is described.
• Locale merge misclassification. Auto-detecting locales from header names (title_en, titleAr) into a JSON column is a silent-corruption class of bug if a column is named ambiguously; unwinding written JSON is manual.
• Schema-derived validation drift. Rules regenerate from the DB, so a migration can change import acceptance without a code review of import behavior. The unique rule generated from schema may also be scoped to the whole table, which is wrong under multi-tenancy.
• Partial-commit semantics. Chunk boundaries mean no all-or-nothing import. Errors are downloadable, but there is no documented rollback, cancel, or resume — recovery is manual SQL.
• Driver and format assumptions. whereJsonContains() lookups, Schema::getColumnListing(), case sensitivity, and Excel parsing all behave differently across MySQL/Postgres/SQLite. The Excel reader dependency isn't named, so the 100K-row memory ceiling is unverified; XLSX at that scale is memory-bound, CSV is not.

Key questions to resolve before committing

1. Which Filament and Laravel versions are we actually on, and is Filament 5 in our 12-month plan?
2. Does upsert mode fire any lifecycle hooks we depend on, and is there a supported way to force per-record save() at scale?
3. How exactly is tenant context carried across the queue boundary — serialized tenant ID on the job, Filament's tenant scoping, or a global scope? Is it verified in a test?
4. What is the upload/file retention policy, and where do error CSVs live? Do they carry PII or cross-tenant rows?
5. What Excel/CSV reader is used, and what is the measured peak memory for a 100K-row XLSX vs CSV?
6. Is there idempotency on job retry, or does a retried chunk duplicate rows when upsert keys are absent?
7. Are there tests and CI in the repo (not just releases)? What is the maintainer's stated support commitment?
8. Does import concurrency on the same table/model have locking, or do two simultaneous imports race on unique keys?

Integration Approach

Stack fit

• Recommend only if we are on Filament 4 with Laravel 10/11+ and PHP 8.2/8.3; otherwise defer.
• Use a dedicated queue connection and named queue (Redis preferred) rather than the default queue, so imports cannot starve transactional jobs and so we can scale workers independently.
• Treat sync queue mode as a staging-only convenience, never production: it converts a 100K-row import into a synchronous web request.
• Pin the constraint (~1.1) and commit the lockfile. Vendor the source into review scope — we should be reading ProcessImportChunk and the relation resolver before go-live, not after.

Migration path

• No upgrade path from a prior version of this package exists for us; this is greenfield adoption. If we currently have bespoke artisan/CSV import scripts, keep them in place as a documented fallback for one quarter.
• Start with the legacy importer as the safety net for any model where data correctness is regulated (financial, billing, user identity).

Compatibility validation

• Run a driver matrix on staging against our real MySQL/Postgres target (and SQLite only for local dev), covering: JSON translatable columns, BelongsTo find-or-create, upsert keys, and tenant-scoped unique validation.
• Test side-by-side with our audit-log package, search-index observer, and tenancy package — those are the three integrations most likely to break silently.

Sequencing

1. Spike (3–5 days), with written exit criteria: one non-critical model, 10K rows, verify (a) observers fire on create path, (b) what happens on the upsert path, (c) tenant isolation from a queue worker, (d) peak memory for XLSX, (e) rollback procedure for a partial import.
2. Adapter layer: wrap the package in a single internal App\Support\Imports\WizardActionFactory (or equivalent) so the vendor namespace appears in fewer than five files. This caps the cost of a future fork or replacement at days, not weeks.
3. Pilot: enable on one internal-only resource behind a feature flag; disable enableUpsert() for the pilot so all writes go through save() and events are consistent.
4. Harden: add a per-model import lock, a tenant-context assertion in the job, a post-import re-sync job to compensate for any upsert event gap, and a cancellation/reaper routine for stuck imports.
5. Roll out resource by resource, then retire legacy importers.

Operational Impact

Maintenance

• Assign clear internal ownership to the backend team; this is a "we may fork it" dependency, not a "we install it and forget it" dependency. Budget roughly 0.2 FTE for the first quarter (review, hardening, runbook), then a few days per quarter tracking upstream and re-validating after our own schema migrations.
• Expect to read the source as primary documentation — the v1.1.0 changelog is effectively the spec for the current behavior. Add contract tests around our three or four critical import paths so an upstream bump cannot silently change semantics.
• Keep a fork-ready posture: MIT license, so forking is legally trivial, but the real contingency cost is a 2–3 week reimplementation if the maintainer disappears. Import wizards are a well-understood problem; the risk is schedule, not feasibility.

Support

• Effectively no vendor SLA: GitHub issues, single maintainer. We must own the runbook (how to read a stuck import, how to download and act on the error CSV, how to reverse a bad batch) and train first-line support on it.
• Define an internal severity policy: a bad import into a regulated table is a P1 with a manual SQL remediation path pre-written.

Scaling

• Throughput is dominated by write path choice: 100K rows via per-record save() means 100K+ queries plus event overhead. Accept the slower path where audit fidelity matters; use upsert only on tables without observer dependencies, and document that decision per resource.
• Excel is CPU- and memory-bound; CSV at the same row count is an order of magnitude cheaper. Prefer CSV for large vendor feeds and reserve XLSX for human-authored files under ~20K rows until memory is measured.
• Progress polling every 5 seconds is fine for tens of concurrent admins; audit the polling cost before enabling for hundreds of users.
• Add a per-model advisory lock so two concurrent imports cannot race on upsert keys or unique constraints.

Failure modes to instrument and alert on

• Queue backlog or worker crash mid-import → import stuck at partial progress with no documented auto-resume. Alert on imports with no progress delta over N minutes.
• Job retry without upsert keys → duplicated rows. Alert on duplicate-cluster detection post-import.
• Lost tenant context across the queue boundary → cross-tenant writes. This is the highest blast-radius failure; add a hard assertion in the job and a post-import integrity check.
• Relation auto-create runaway → alert if a single import creates more than a threshold of new related records; require review.
• Validation drift after a migration → run the pilot import suite in CI against a migrated schema.
• Orphaned uploads and error CSVs (PII retention) → schedule cleanup and confirm tenant-scoped access to error downloads.
• Deploy-time asset rebuild (filament:assets) breaking admin styles if skipped → add to the deploy checklist.

Ramp-up

• Developer: under a day to a first working import, roughly a week to a trusted production path including the adapter and tests.
• Ops/support: 1–2 days for the runbook and a tabletop exercise on a deliberately failed import.
• End users: low training cost — reverse mapping and snake_case auto-matching substantially reduce mapping effort versus header-first tools, and locale merge is a real win for multilingual catalogs. Publish a short guide and consider hiding the upsert and merge-translation toggles from non-admin roles, since both are one-click paths to hard-to-reverse data states.

Verdict for planning purposes: technically attractive and unusually well-scoped for its size, but the adoption signal (12 stars, 0 dependents, single maintainer) plus the upsert/event asymmetry and unverified tenant isolation make this a "spike with explicit exit criteria and a fork contingency," not an unconditional adopt. Proceed only behind an internal adapter, on a dedicated queue, with upsert disabled until the event gap is proven safe for each target table.