Nova Items Field Laravel Package

Technical Evaluation

Architecture fit. The package is a leaf Nova field: one PHP field class in src/ and one Vue 2 component in resources/js/, with no service provider touching the request lifecycle. It maps a single JSON column to a repeatable, drag-sortable editor whose rows are defined by whatever sub-fields you pass to ->fields([...]). That is a narrow, well-bounded contract, which is exactly the profile a TPM wants for a tactical admin-tooling buy: small blast radius, no runtime coupling to queues, auth, or routing, and no schema migration beyond the one JSON column.

It is the right architecture only under a specific set of conditions: the list is edited as a whole, belongs to one parent model, is flat (not nested), and is not a first-class queryable entity. The moment contents need server-side search, filtering, sorting, reporting, or relationships to other models, the correct answer is hasMany plus a Nova relationship field, and this package converts from accelerator into technical debt. That is a scoping rule a TPM can apply in a design review in under five minutes.

Integration feasibility. High, on Nova 3.x only. composer require dillingham/nova-items-field:0.6.*, make the backing column $table->json(...)->nullable(), register the field on a resource. Same-day for a single use case. The critical gate is composer show laravel/nova before anything else: this is a Vue 2 / Laravel Mix-era component, and on Nova 4 (Vue 3) or Nova 5 (Vite/PHP 8.1+) it will almost certainly fail to build. That failure is loud and build-time — a staging failure, not silent production corruption — which makes it tolerable tactically and unacceptable strategically.

Technical risk. Ranked, with the PM-relevant framing:

• Nova upgrade expiry date (dominant). Adoption is time-boxed to your current Nova major. Port cost is roughly 3–5 engineer-days (Vue 3 + Vite rebuild, including tests), and a fork must start from 0.6, not earlier, to inherit the nullable fix from PR #14. MIT licensing makes forking legally unencumbered.
• Whole-array write semantics. Two admins editing different rows of the same record silently clobber each other. No per-item locking, no partial writes. Acceptable for low-concurrency internal ops; disqualifying where concurrent editing is expected.
• No schema enforcement on the JSON. Types drift ("1" vs 1, null vs [], orphaned keys). Anything downstream — API, export, analytics — must handle it. The package does not enforce shape; validation lives entirely in the resource's rules() as wildcard per-key rules plus an array-level bound.
• Dependency governance. Single maintainer, pre-1.0, last release 2020-09-16, 111 stars, 0 reported dependents, no vendor support (a Nova license does not extend to third-party fields). The 0.6 community merge is a mild positive signal, not a maintenance commitment.
• CI/security posture. The private laravel/nova dependency means builds require Nova repo auth in CI, and security scanning on that private dependency is limited. Every engineer touching the field inherits that constraint.

Key questions to answer before committing.

1. What Nova major are we on today, and what is the committed upgrade date to 4 or 5?
2. Is null semantically distinct from [] in this domain — and are we willing to fund downstream branching on two "empty" states? If not, normalize to [] in the resource layer and document it in one place.
3. Is this list ever read outside Nova (API, exports, analytics, search)? If yes, who owns normalization?
4. What is the expected concurrent-edit rate on these records?
5. Who is the named internal owner of the fork, decided before adoption, not after?

Integration Approach

Stack fit. Requires Laravel Nova 3.x with a JSON (not text) column and model $casts that don't mangle the array. Pin 0.6.* exactly — not ^0.6 — because pre-1.0 semantics mean a minor bump may carry a breaking change, and 0.6 is the tag that carries nullable support. Composes as a leaf field alongside normal Nova fields on the same resource; no dependency on queues, auth, or routing. Nova's standard field API handles readonly() and conditionals — the package adds nothing there, so gate write access with it rather than expecting the package to.

Migration path. If the array is currently edited by hand in a DB client, in a config file, or via ad-hoc scripts, the migration is organizational, not technical: the shape must be documented as a small public contract between the resource layer and any downstream consumer, and validated in exactly one place. If the data currently lives in a relational table and only the editing is being moved into Nova, stop — this is the wrong tool; keep hasMany. There is no data migration burden for the greenfield case beyond adding the column.

Compatibility. Sub-fields define the shape; keep it flat. Nested structures are out of scope and won't render reliably. Built-in drag-and-drop reorder is free and persists as array order in the JSON — no config, but do not rely on that order server-side for anything requiring deterministic sorting; sort explicitly on read. Extension points are minimal by design: if you need min/max item counts, nested repeaters, or per-row conditional logic, verify it exists during the spike rather than assuming — 0.6 adds nullability only.

Sequencing. Run this as a time-boxed spike with a decision gate, not a rollout:

1. Confirm Nova version (composer show laravel/nova). Hard stop if not 3.x.
2. Pin and install 0.6.*; add the nullable JSON column.
3. Prove the round-trip on a low-risk list — feature bullets, menu links, FAQ entries. Create a row, add two items, drag to reorder, save, reload, and confirm the JSON in the DB matches the UI. Then create a record with null in that column and confirm it loads and saves without coercing to [].
4. Encode validation in the resource's rules(); decide and document the null vs [] contract.
5. Ship read-only first, gate writes behind a permission, and observe a full lossless round-trip including null before granting edit access.
6. Grant edit access to a named ops group and measure ticket volume for a defined period. That evidence — not the package — is the durable output.

Operational Impact

Maintenance. Effectively zero upstream maintenance and that is the point: nobody is obligated to fix this. Support is GitHub issues with uncertain response times, and a Nova license does not extend to third-party fields. The realistic maintenance model is an internally owned fork with a named owner, a pinned version in composer.json, and a line item on the Nova upgrade roadmap that converts the fork cost (3–5 engineer-days) from a surprise into a planned task. Treat the field as an experiment harness with a defined end date.

Support. No vendor SLA. Internal support falls to whoever owns the fork. Debugging is genuinely cheap because the surface is small — read the one PHP field class and the one Vue component, that is the whole package. Practical triage: field renders empty → confirm the column is json not text and $casts aren't mangling the array; save silently no-ops → check validation rules aren't rejecting the array-level key; drag-drop order doesn't persist → confirm the whole array is being saved, since partial writes aren't supported.

Scaling. Two dimensions, and only one of them degrades:

• Data volume is fine for lists (a handful to low tens of items). Add an array-level max:N rule as a guardrail; nothing in the package bounds it.
• Concurrency does not scale at all. Whole-array writes mean the last writer wins, silently, at the row-of-items granularity. Keep this to low-concurrency internal ops; if two or more people routinely edit the same record's list, move to hasMany.

The real scaling ceiling is organizational: each additional resource using the field multiplies the surface you must re-verify after a Nova upgrade.

Failure modes. Ordered by likelihood and severity:

• Nova upgrade build failure — high likelihood at Nova 4/5, loud, caught at build time. Good failure, but it forces a fork decision on someone else's schedule.
• Lost updates from concurrent edits — silent, no audit trail, worst failure mode because it's invisible. Mitigate with permissions gating and low-concurrency scoping; there is no per-item locking to enable.
• JSON type drift — silent, discovered downstream in exports, APIs, or analytics. Mitigate by normalizing on read or in a dedicated resource layer, and standardizing on one "empty" representation if null isn't meaningful.
• Downstream breakage from the null/[] split — introduced by adopting 0.6's nullable support. Every consumer now branches on two empty states; decide the semantics once, document them, validate accordingly.
• CI breakage from missing Nova credentials — operational friction, not a data risk.

Ramp-up. Low for engineers — a competent Laravel dev is productive in hours, because there is one field class and one Vue component to read. The ramp-up that matters is for operators: run the read-only period, then a short enablement session covering add, remove, and drag-reorder, and confirm they understand that saving replaces the whole list. Budget the PM time for the decision, the documented data contract, and the named fork owner; budget the engineering time for the spike and for the upgrade-roadmap line item. Then measure routine engineering tickets on those fields before and after — that number is the business case.