Nova Multiselect Field Laravel Package

Technical Evaluation

Architecture fit

• Purpose-built Nova field (a Composer package), not a standalone UI library. It only delivers value if the admin surface is Laravel Nova 5; without Nova, the package is unusable and the evaluation is moot.
• Extends Nova's native Select field contract. It stores selections as a stringified JSON array in a text-based column by default, or as native JSON via saveAsJSON() when the DB column is a JSON type.
• Ships a Vue frontend component (form/detail/index views) with overridable template hooks (NovaMultiselectDetailFieldValue, FormFieldTag), so branding/UX can be tailored without forking.
• Includes useful primitives for real admin UX: async option querying (asyncResource, api), option groups, dependency between fields (optionsDependOn), distinct option pools, taggable, reorderable, and belongsToMany / belongsTo relationship modes.

Integration feasibility

• Installation is a single composer require outl1ne/nova-multiselect-field; no migrations, service-provider wiring, or asset build step required.
• Field declaration is idiomatic and low-ceremony, mirroring Nova's Select API. A TPM can reasonably scope this as a same-sprint deliverable for a competent Laravel dev.
• Optional localization publish command and component overrides are the only customization hooks that touch app JS/app.js, which is standard Nova practice.

Technical risk

• Hard coupling to Nova's commercial major version. Requirements are php: ^8.1 and laravel/nova: ^5.0; older Nova majors live on separate maintained branches (v4, v3). This forces a coordinated upgrade whenever Nova ships a breaking major.
• Storage model is the biggest architectural concern. Default stringified-JSON-in-text means selections are opaque to SQL filtering/indexing; consumers must decode on read. saveAsJSON() only helps if the schema is already JSON-typed. This leaks into reporting, exports, and any downstream service reading the column.
• Vendor/supply-chain concentration. Single-maintainer package (MIT, forkable) with an active changelog and release history, but no commercial SLA. The Dependents: 0 signal is expected for a leaf Nova field (apps consume it, not packages) but should not be read as proof of adoption — validate against our own repo scan.
• Data anomaly to verify: the reported last release date (2026-06-10) is in the future relative to typical evaluation windows. Treat as a metadata error until confirmed against Packagist.
• Historical namespace migration (OptimistDigital\… → Outl1ne\… in v4) is a precedent that the package has already forced a breaking rename once; plan for similar churn.

Key questions

1. Are we standardized on Nova 5, and is the Nova license renewal budgeted? Any imminent Nova major upgrade?
2. Do the target tables use JSON columns (enabling saveAsJSON) or legacy text/varchar? Who else reads those columns?
3. What is the async-search strategy for belongsToMany — will we enforce belongsToMany(..., false) only on bounded tables?
4. Can we accept single-maintainer risk, or do we need a maintained fork/patched vendored copy?
5. Does the distinct/optionsDependOn UX map to real business rules, or are we inventing complexity?

Integration Approach

Stack fit

• Fits any Laravel app already running Nova 5 on PHP 8.1+. No additional runtime, queue, or infra dependency.
• Best fit: admin/config surfaces where users pick from curated lists (categories, tags, regions, teams) and relationship assignment via belongsToMany.
• Poor fit: high-cardinality free-text taxonomies where taggable() would create ungoverned values, or any surface needing SQL-level analytics on the selection.

Migration path

• Greenfield: composer require, publish translations (optional), declare fields in Resources, choose storage type per column.
• Existing fields: migrate Select/native relation fields to Multiselect one resource at a time; watch for value-shape changes (single string vs JSON array) and backfill existing rows to the stringified array format.
• Nova 4 → 5: confirm the ^5.0 branch supports the fields in use; if stuck on Nova 4, pin the nova-v4 branch explicitly rather than relying on Composer resolution.

Compatibility

• PHP ^8.1 and Nova ^5.0 are explicit gates; older Nova requires branch pins. No reported peer conflicts beyond that.
• Frontend overrides are Vue-component-contract dependent; a Nova frontend upgrade could break custom app.js components before the package itself breaks.

Sequencing

1. Confirm Nova 5 + PHP 8.1 baseline and license status.
2. Pick storage strategy per table (text vs JSON) and document the read contract (values are JSON-decoded arrays).
3. Implement one pilot resource with options() first; add asyncResource / belongsToMany only where bounded.
4. Layer advanced features (distinct, optionsDependOn, taggable) after the pilot validates UX and data shape.
5. Publish translations and add component overrides last, once the base field is stable.

Operational Impact

Maintenance

• Low ongoing effort: no migrations, no background jobs, no asset pipeline. Upgrades are Composer-level and gated by Nova majors.
• Track the package's release cadence and Nova's major releases; expect to re-pin branches on Nova upgrades. Maintain an internal fork only if the maintainer goes quiet or a security patch lags.

Support

• Community-only support via GitHub issues; no vendor SLA. Nova itself carries commercial support, which partially de-risks the surrounding platform.
• MIT license means we can fork and patch; budget a "break-glass" owner (a Laravel dev) rather than a dedicated team.

Scaling

• Async search (asyncResource, custom api) is the correct pattern for large tables; optionsLimit (default 1000) caps render cost.
• belongsToMany(..., false) eager-loads all options — enforce a bounded-row rule or accept admin page latency.
• Index rendering is bounded by indexValueDisplayLimit / indexCharDisplayLimit; set these deliberately to avoid slow list views.
• The text-column storage model will become the scaling bottleneck for reporting, not for the UI.

Failure modes

• Schema mismatch: saveAsJSON() enabled on a non-JSON column (or vice versa) silently corrupts reads.
• Unbounded option loads: belongsToMany without async on a large table degrades the admin.
• Dependency breakage: optionsDependOn leaves orphaned values when the parent field changes; needs validation rules.
• Ungoverned taggable values: free-form tags drift from the canonical taxonomy.
• Custom api endpoints: auth/tenant scoping must be enforced server-side; the package only passes a search param.
• Nova major upgrade: frontend component contract changes can break overridden templates before the package fails.

Ramp-up

• Very low for any Laravel dev familiar with Nova: the README covers installation, options, groups, dependencies, and belongsToMany with copy-paste examples.
• Main learning curve is data-contract discipline (stringified JSON vs JSON column) and Nova version/branch pinning, not the package API itself.
• Recommend a half-day spike on the pilot resource plus a short internal note documenting the storage contract for downstream consumers.