Nova Import Laravel Package

Technical Evaluation

Architecture fit. This is a Nova-surface tool, not a platform component: it bolts an upload → map columns → validate → persist workflow onto existing Nova resource pages, sitting on top of maatwebsite/excel ^3.1 and calling Model::create() directly. Architecturally it fits only one shape of problem — flat, single-table Eloquent models with scalar attributes, imported by back-office admins at low-to-medium volume. Anything relational, deduplicated, audited, scheduled, or high-volume is outside its design envelope. From a product standpoint that is not a flaw so much as a boundary: the tool defines a clean MVP of "admin bulk import" and nothing more. The relevant TPM judgement is whether our actual demand lives inside that boundary. If ops needs to seed a reference table or migrate a spreadsheet once a quarter, it fits. If the job is customer-facing ingestion or a recurring data pipeline, it is the wrong shape entirely and adopting it would create a false sense of capability.

Integration feasibility. On Nova 3 / Laravel 6–8 / PHP 7.x the install is genuinely quick — Composer require, publish provider and assets, register the tool in NovaServiceProvider. The feasibility question is almost entirely a version question. Nova 4/5 rebuilt the frontend toolchain; the bundled Vue 2 asset bundle will not compile or mount, and that failure surfaces late (at nova:publish), which is exactly the kind of surprise that burns a sprint. The second feasibility gate is Composer: maatwebsite/excel ^3.1 is the most likely conflict if we already run export or reporting packages. Both gates are answerable in a one-to-three day spike on a scratch install at our exact versions, and they should be answered before any roadmap commitment is made.

Technical risk. Four risks matter at the product level. Maturity: last release August 2020, 70 stars, zero dependents, no maintainer backstop and no security patching channel — adopting it means we become the maintainer. Data integrity: the import runs synchronously inside an admin request, partial writes leave no trace, there is no audit trail, and there is no upsert semantics, so a re-run duplicates rows or trips unique constraints. Silent failure modes: BOM'd or semicolon-delimited CSVs can map zero columns without erroring, Excel mangles leading-zero identifiers and serial dates, and mass-assignment guards can drop mapped columns while reporting success. Access control: canSee() on the tool is effectively the only gate, since the upload endpoint is authenticated but not otherwise authorized. None of these is disqualifying for an internal pilot; all of them are disqualifying for financially or compliance-relevant data.

Key questions. (1) Are we on Nova 3 or Nova 4/5 — this single fact decides install-versus-reimplement. (2) Does our demand sit inside the boundary (flat tables, back-office users, low volume) or outside it (relational, dedupe, scheduled, audited)? (3) Is "working in six weeks" an acceptable bar, or is "still working after the next Nova upgrade" the actual acceptance criterion? (4) Who is the named owner of the fork and its upgrade path? (5) What is the honest commercial baseline — Techsemicolon, Kirschbaum, or a thin internal build — against which "free" is being compared?

Integration Approach

Stack fit. The fit is narrow and version-pinned: Nova 3, Laravel 6–8, PHP 7.2–7.4, maatwebsite/excel ^3.1. That is a real stack, just not a current one. The TPM framing should be explicit — this is the "borrow" option in a build/buy/borrow comparison, a tactical stopgap that front-loads the demand question and defers the ownership question. It is not a strategic import platform and should never be positioned as one to stakeholders.

Migration path. Two paths diverge at the Nova version check. On Nova 3, the path is install → spike → fork → pin. On Nova 4/5, the honest path is do not install: treat the repository as a product specification for a thin internal build. The upload → map → validate → import flow, the mapping payload contract, and the Vue modal together describe a usable spec for a few days of engineering, and a "no" on adoption still produces a cheaper way forward. Either way, the decision memo should record which path was taken and why, because the answer will be re-litigated at the next upgrade.

Compatibility. Three compatibility layers need independent confirmation before committing: Nova's frontend toolchain (asset build), Composer's dependency graph (composer why maatwebsite/excel before and after), and our target models' fillable/guarded configuration. The first two are binary pass/fail in a spike; the third is a configuration decision we control. Header-matching behaviour deserves a compatibility note of its own — it is literal, so a BOM or trailing space silently zeroes the mapping, and users will not report it as a bug, they will report it as "the import doesn't work."

Sequencing. Run a 1–3 day spike on a scratch Nova install at our exact versions against one boring reference table (countries, categories, carriers) with a 40–100 row CSV. Diff the result row by row — that surfaces most of the gotchas in under an hour without touching anything important. If the spike passes: fork privately, pin the commit, add fixture-based tests, gate behind a permission, tag every import with a batch ID, and run one real resource end-to-end in staging. Only then consider a second resource. If the spike fails, convert the findings into the spec and take the build path. Do not sequence this as "adopt, then evaluate."

Operational Impact

Maintenance. We become the maintainer. Budget roughly 2–4 engineer-days per Nova major upgrade, plus the ongoing cost of a private fork that nobody upstream is patching. That is a permanent, bounded cost against a bounded benefit — acceptable for an internal admin convenience, not acceptable if the capability quietly becomes load-bearing for revenue or compliance workflows. The governance move is to register this in a "vendored/at-risk" inventory with a named owner on day one, not after the first upgrade breaks it.

Support. There is no vendor, no security channel, and no community large enough to rely on. Support is internal only: a runbook, a README the package never had, and a documented escalation path to the fork owner. Users will need explicit guidance on accepted formats (CSV preferred over Excel, to dodge identifier and date mangling), expected headers, and row limits — otherwise every failed import becomes a support ticket routed to engineering.

Scaling. The synchronous ceiling is lower than intuition suggests: max_execution_time, memory_limit, and post_max_size will stop the import in the low thousands of rows, well before the database cares. Row caps must be enforced server-side, not in the Vue component, which anyone can bypass. Above a few hundred rows, route through a queue — but verify the package's built-in queue path against our driver before trusting it, since the promise and implementation have drifted. The pragmatic pattern is to have the upload handler store the file and dispatch our own job that reuses the parser and mapping payload, chunking at 500–1000 rows with a transaction per chunk and progress written to a batch record.

Failure modes. The incident-shaped one is partial writes: a mid-file timeout with no transaction and no batch tag leaves an unknown table state with no way to identify or reverse it. The second is silent row loss — validation failures flash to the browser and evaporate, making "why didn't row 47 import?" unanswerable. The third is duplicate creation on re-run. All three are mitigable with a batch UUID column (or small import_batches table) written inside a transaction; that single addition buys rollback, an audit answer to "who imported this, when," and a way to reason about half-finished runs. Retrofitting audit later is a migration, not a patch, so decide now whether audit is a requirement — if it is, this package is the wrong starting point.

Ramp-up. Fast on Nova 3: hours to first successful import of a flat reference table, days to a production-gated single-resource rollout with a fork and tests. Slow and deliberately so on Nova 4/5, where the ramp is actually the spec-to-build path and should be estimated as such rather than as "install friction." The stakeholder pitch that survives contact with reality is a low-risk admin-productivity pilot with measurable hours-saved-per-month, scoped explicitly to internal back-office data — not an import platform, nothing customer-facing, and with the ownership cost stated up front rather than discovered at the next Nova upgrade.