Nova Belongsto Depend Laravel Package

Technical Evaluation

Architecture fit. This is a leaf dependency, not a platform component: a PHP BelongsTo subclass, a precompiled Vue asset, and a small vendor route that resolves dependent options. It owns no schema, migrations, service boundary, queue, or business workflow. Fit is therefore binary — it creates leverage only if the back-office surface is Laravel Nova, and zero leverage otherwise. Where Nova is in production, it addresses a recurring, well-understood admin need (country → state, client → project, category → subcategory) that would otherwise be hand-built.

Integration feasibility. Expected to be low-friction: composer require, Nova auto-discovery, no config publishing, no database changes, no manual provider registration. The only real prerequisite is commercial Nova Composer credentials present in every environment — CI, staging, and new developer laptops. That is the usual first blocker, and a TPM should confirm it before writing the ticket. Rollback is a field-class swap plus dependency removal, which is what makes a scoped trial defensible.

Technical risk. The dominant risk is lifecycle, not code quality. Last release 2022-06-21 sits at the Nova 3 → 4 boundary (Vue 2 → Vue 3), Nova 5 support is unverified, there is one maintainer, zero dependents, and the frontend ships as a compiled asset with no build chain — the PHP is auditable in an afternoon, the JS is not patchable cheaply. Security exposure is low (no auth surface, no file I/O, no complex processing). The realistic failure is silent UI breakage after an upgrade, not compromise. MIT licensing keeps the fallback executable without procurement friction, which is precisely why a limited trial is rational.

Key questions. Each of these unblocks a specific decision, so a TPM should treat them as spike exit criteria rather than open-ended curiosity:

1. Which Nova major/minor runs in production, and does the compiled field mount against it? → go/no-go.
2. Is filtering a constrained server-side query or fetch-all-then-filter in JS? → if the latter, stop; it is a data-correctness hazard on large lookup tables.
3. Does the field behave on edit forms, where parent resolution order differs from create? → determines whether the trial covers existing records or only new entry.
4. Can Nova's native dependsOn() + a relatable() closure reach parity in ~100 owned lines? → the build-vs-buy answer.
5. Is there an active fork or maintained successor with the same API surface? → cheap insurance.
6. Who is the named owner and what is the documented fallback? → the condition of adoption, not an afterthought.

Decision framing. The real choice is not "adopt vs. do nothing," it is "adopt an unmaintained field vs. own ~100 lines." Because reimplementation is cheap and ramp-up is hours, the package's value is convenience — which caps how much upgrade risk is rational to accept. Position this as a data-integrity and admin-speed lever competing for maintenance budget, never for roadmap priority.

Integration Approach

Stack fit. Additive to Laravel + Nova, imposing no frontend framework, state manager, or build tooling unless the team chooses to rebuild the asset. Scope is one field type, so adoption can be confined to one or two resources and judged on real admin forms rather than a synthetic demo.

Migration path. Greenfield addition, not a data migration: no backfill, no schema coupling, no persisted state. The only migration-shaped work is replacing existing plain BelongsTo fields with the dependent variant, reversible per field. The exit path — revert to native BelongsTo or port the filter logic into an in-house field — is cheap enough that a trial carries negligible sunk cost.

Compatibility. Pin the exact package version and the Nova minor in composer.lock, and add an explicit laravel/nova constraint so an upgrade cannot silently drag the field onto an unsupported runtime. Validate against the Nova version running today and the one expected in twelve months; if it only works on an older Nova, cap its useful life at the current upgrade calendar and say so in the ticket rather than discovering it later.

Sequencing. Gates, not phases — each step has an owner, a timebox, and a defined stop condition.

1. Spike (0.5–1 day, throwaway branch, Nova-fluent engineer). One real cascading pair; exercise create, edit, validation-error, searchable, empty-state, and nullable-parent. Record the exact Nova version where it mounts. Gate: does it work at all?
2. Build-vs-buy check (same spike, parallel). Attempt native dependsOn() + relatable(). If it reaches parity, take the in-house field, close the ticket, buy nothing. Gate: is the convenience worth a third-party line item?
3. Narrow rollout (one resource). Normal PR review, plus a code comment flagging the package as unmaintained, a named owner, and a written fallback. Gate: is ownership real or nominal?
4. Fork decision. If adopted beyond the trial, vendor or fork under the org so PHP is patchable and JS rebuildable. Gate: fork before broadening — forking under incident pressure is materially more expensive.
5. Broaden. Only after the field survives one release cycle and ideally one Nova upgrade.

Operational Impact

Maintenance. Effectively zero while Nova is frozen, and lumpy at every Nova major. Budget it as a known upgrade-tax line item, not a self-maintaining dependency. Because the asset is compiled, hotfixing the UI side is harder than the PHP's size implies — the practical rule is fork early, not during an incident.

Support. No vendor SLA, no issue-triage guarantee, thin documentation. Internal volume is low because the field is narrow, but it spikes unpredictably at upgrade time and lands on whoever owns the Nova admin. Acceptable for a sub-500-line field; risky if treated as a black box.

Scaling. Runtime scaling is not a field-level concern — one query per interaction. The scaling question is query shape: confirm the filter is a constrained server-side query, not fetch-all-then-filter, which degrades on large lookup tables and can silently widen the option list into a correctness problem. The larger constraint is organizational: an unmaintained package with a compiled asset becomes a "don't touch the admin" taboo the moment the original adopter leaves. Documenting owner and fallback up front is the mitigation.

Failure modes. Each maps to a TPM control:

• Silent no-op after a Nova upgrade — the field renders, dependent options never refresh, no error surfaces, and operators save wrong data. Control: an explicit line on the Nova upgrade checklist plus a maintained smoke test on the dependent form.
• Stale or empty options on edit forms triggered by field-resolution ordering. Control: edit-form coverage in the spike, not just create.
• Over-broad option lists from unparameterized filtering — a data-correctness risk, not a UX nit. Control: query-shape verification before rollout.
• Repository archived with no response to a future compatibility issue. Control: a fork already in hand; without it, this is a hard stop on the Nova upgrade.

Ramp-up. Hours for a developer already fluent in Nova's field lifecycle, most of it Nova rather than the package. Because ramp-up and reimplementation cost are both low, the package's value is convenience, not capability — which caps rational upgrade risk and pushes toward an in-house field the moment the spike shows friction.

Measurement. Fund it only where admin speed or data integrity carries operational value you can point at: invalid parent/child combinations avoided, records corrected per week, back-office entry time per form. Baseline those before rollout on the one resource in scope, review after one release cycle, and only then argue for broadening. Do not let a lightweight field justify deferring a Nova upgrade, and do not let it become a platform dependency nobody examined.