Custom Relationship Field Laravel Package

Product Decisions This Supports

• Shipping "curated list" features without a schema commitment. Featured products, editorial collections, pinned resources, hand-picked cross-sell sets, related-article blocks — these are admin-authored groupings whose shape changes every sprint. This Nova field presents and edits them as if they were a real relationship, so the work package shrinks from "migration + pivot table + model changes + bespoke Vue field" to "a Nova resource configuration change." The value is time-to-demo and time-to-internal-tool, not architectural elegance.

• Build vs. buy on back-office surface area. The buy alternative is a bespoke Nova field: Vue component, search/select/attach UX, backend resolution, policy-aware scoping, tests, and ongoing maintenance. That's a multi-day squad commitment against a surface no customer ever sees. For internal-only admin workflows, adopting an MIT-licensed field and pinning it is usually the right trade — provided the exit path is planned on day one.

• Roadmap sequencing during discovery. While the domain model is still contested ("are these actually many-to-many? is this a taxonomy or an ordered list?"), this field lets you ship the editor workflow and validate it with real content operators before committing to a relational model you may throw away. It buys learning cheaply. It is a deferral, not a permanence decision.

• MVP and pilot scoping. Useful where normalization is deliberately postponed to hit a pilot date — a sales-demo or pilot dataset with plausible-looking linked records, curated through the admin by non-engineers.

• Risk and capacity decisions it should inform. Because the relationship is emulated at the Nova layer only, adopting this field is also a decision to own: the options query, the authorization scoping, orphaned-ID cleanup, Nova-upgrade regression testing, and a fork path. Those are recurring costs a PM should book against the team, not assume away.

• Decisions it should explicitly NOT drive: pricing or entitlement logic, anything a customer or partner API reads, anything a report, export, analytics job, or search index joins on, anything requiring referential integrity or cascade behavior. No downstream system can see this relationship. If a feature needs the relationship to be real to anything other than an admin screen, the tool choice has already been made for you — build the pivot table.

• A documented "not yet" answer. When a stakeholder asks for a new grouping feature, this package supports the answer "admin-editable now, real data model when a consumer appears." That deferral is a legitimate roadmap position only if someone owns the trigger condition for promoting it.

When to Consider This Package

Adopt when all of these hold:

• The stack is Laravel Nova. This is a Nova field; without Nova it delivers nothing. That's the non-negotiable gate — confirm Nova version and upgrade cadence before evaluating anything else.
• The relationship is admin-curated and machine-invisible. Humans attach and detach; no service, API, warehouse sync, report, or export consumes it.
• The set is small and bounded — tens of links per record, low admin concurrency. There is no normalized pivot, so scale becomes a query-design problem your team now owns.
• Speed is the point. A real pivot table isn't justified by the feature's expected lifespan or by the migration cost.
• You will treat it as a vendored utility, not a platform. Pin to v1.1.3 or later (it fixes a buildIndexQuery crash on bulk "select all" in a BelongsToMany context), wrap it in a project-local field class so it's replaceable in one file, and budget for a fork. Signal check: 33 stars, 0 dependents, single visible maintainer, MIT, last release 2024-07-18, low opportunity score. None of that disqualifies an internal admin widget — but it disqualifies anything load-bearing.

Look elsewhere when any of these hold:

• Not on Nova — use native BelongsToMany/HasMany, or a JSON-cast column plus your own UI.
• You need database-level integrity — foreign keys, uniqueness constraints, cascades, JOIN-able reporting.
• The relationship must be visible to APIs, exports, or analytics. Emulated relations are invisible outside the admin panel, full stop.
• You need to filter or aggregate by related IDs at scale, or run high-cardinality bulk operations.
• You need a support SLA or an active community. Neither exists; budget self-support and a named internal owner.
• The data model is stable and load-bearing. Then do the boring thing and build the pivot — cheaper over two years than the workaround plus its cleanup jobs.

Adoption checklist a PM can hold engineering to: Nova-version compatibility confirmed on a pinned release; one low-risk pilot resource only; the options query moved onto the model as a named, reusable method; a project-local wrapper field in place; explicit tenant/role scoping inside every options callback; a capped option list so "select all" can't materialize an unrenderable ID set; a scheduled orphan-cleanup job if deletes matter; a Nova-upgrade test step added to the release checklist; and a written note in the resource stating what backs the field and that no API reads it.

How to Pitch It (Stakeholders)

To executives and product leadership: "This lets us ship a class of admin-authored curation features — featured items, editorial collections, hand-picked cross-sell — in days instead of sprints, with no database migration. It's an MIT-licensed Nova widget backed by a JSON column, so it's cheap to try and cheap to remove. The catch is that it's an admin-panel-only convenience: nothing outside the admin can read the relationship, and we own the maintenance. I'd scope it to internal tooling and pilots, not to anything a customer-facing system depends on."

To engineering: "One class, one maintainer, 33 stars, zero dependents, last release mid-2024. Treat it as a vendored utility: pin ^1.1.3, wrap it in a single project-local field class so a Nova major bump or a fork is a one-file edit, and keep every ->options() closure scoped by tenant/role — Nova policies don't constrain those queries. Store IDs in a JSON-cast column, resolve them explicitly in controllers with whereIn (and re-sort in PHP if order matters), and add orphan cleanup plus a Nova-upgrade regression step to the release checklist. It is not a relationship: no whereHas, no eager loading, no cascades."

To design and content ops: "The editor looks and behaves like a real relationship picker — search, select, attach, save. What you curate is the truth for that admin screen. Note the ordering caveat and that the list is bounded, so very large catalogs will be filtered rather than fully selectable."

The trigger condition to write down and assign: the first time any API, export, report, or analytics job needs to read this grouping, the deferral ends — build the pivot table and delete the custom field in the same PR. Two sources of truth diverge on the first edit through the other path.