Statamic Field Item Relationship Laravel Package

Technical Evaluation

What it is: eminos/statamic-field-item-relationship is a Statamic addon (Laravel-ecosystem, CP-facing) providing a relationship fieldtype plus a frontend {{ fir }} tag. It is not a general-purpose Laravel package — its value is entirely inside a Statamic 6 control panel and Antlers/Blade templating layer.

Architecture fit: Good fit for teams already modeling content in Statamic who need item-to-item relationships without writing a bespoke fieldtype. The addon stores data through Statamic's own content conventions rather than introducing a parallel persistence layer, so it inherits Statamic's multi-site, revision, and driver behavior. The v2.0 fix — reading publish container values instead of DOM/component lookup — moves the addon from a fragile CP-internals hack toward the supported reactivity contract, which is a genuine architectural improvement, not just a bug fix.

Integration feasibility: Straightforward mechanically (composer require + addon registration), but gated hard on Statamic 6 / Vue 3. Any stack still on Statamic 5 is pinned to v1.4.1 and gets no further fixes. Integration cost is therefore dominated by the Statamic upgrade, not the addon.

Technical risk:

• Version coupling (highest): v2.0 is a breaking platform gate, not an incremental release. Upgrade timing is dictated by Statamic 6 readiness across the whole addon set.
• Data-shape semantics: "Save as: Index" for simple string arrays introduces a storage choice that is cheap now and expensive to reverse once authors have created content against it. This is a content-modeling decision disguised as a field setting.
• Test coverage asymmetry: The new Pest suite covers the {{ fir }} tag only. The CP fieldtype UI — the surface most likely to regress against Statamic internals — remains untested. CI green does not mean the authoring experience works.
• Bus factor: Single-maintainer addon with no commercial SLA; the v2.0 changelog is the only support commitment available.

Key questions for the maintainer/team:

1. Does "Save as: Index" alter the stored structure in a way that requires migrating existing entries, or is it opt-in per field only?
2. Are there breaking changes to {{ fir }} template output, or is the Pest suite purely additive?
3. Does the publish-container change rely on a Statamic 6-only API (i.e. is it truly inseparable from the Vue 3 bump)?
4. What is the support expectation for v1.4.1 on Statamic 5 — security-only, or frozen?
5. Is multi-site relationship resolution covered anywhere in testing?
6. What is the maintainer's stated policy for Statamic minor-version compatibility?

Integration Approach

Stack fit: Laravel + Statamic 6 (Vue 3 CP), Composer-managed, deployed like any addon. Does not apply to Blade-only Laravel applications or to Statamic sites running a headless-only content pipeline that never uses the CP fieldtype (though the {{ fir }} tag still matters).

Migration path: Two distinct paths, and the TPM should not conflate them:

• Statamic 5 → 6 in place: pin 1.4.1, upgrade Statamic and all addons together, then bump this addon to 2.0 in the same change window. There is no intermediate state.
• Greenfield on Statamic 6: adopt 2.0 directly; no migration work, but decide index-vs-keyed array storage before authoring begins.

Compatibility checks before commit:

• Inventory every other addon/fieldtype for Statamic 6 support; this addon is a passenger, not a driver.
• Verify the fieldtype's config schema survives the major bump (existing field YAML still loads and renders).
• Test {{ fir }} output against representative templates — tag behavior is the one thing with automated coverage, so regressions here should surface early, but confirm your usage patterns are actually exercised.
• Confirm multi-site: relationship values resolving per-site vs. shared across sites.

Sequencing:

1. Freeze new content authoring on fields of this type during the upgrade window (limits index-storage divergence).
2. Spike in staging with a content subset: author, save, re-save, and render through {{ fir }}.
3. Audit any existing simple-string-array fields before enabling "Save as: Index".
4. Ship to production with a documented rollback pin to 1.4.1 and a content snapshot.
5. Re-run CP smoke tests after every subsequent Statamic minor bump.

Operational Impact

Maintenance: Low code surface, but the maintenance burden is not zero — it is deferred onto Statamic upgrade cycles. Budget a recurring QA task per Statamic minor release specifically for this fieldtype's CP behavior, since CI will not catch it. Track the repo for the next 2.x patch; a single-maintainer addon that just went through a Vue 3 rewrite is statistically likely to ship follow-up fixes.

Support: No vendor SLA. Internal ownership must be explicit: whoever owns the CMS upgrade owns this addon's regression testing. Authors will report the failure mode that matters ("I can't pick the right item any more"), which is a CP bug, not a templating bug — the Pest suite will not have caught it. Establish a manual CP checklist: open field, confirm sibling-reactive options refresh when a related field changes, save, re-open, verify persisted values.

Scaling: Storage follows Statamic's driver (flat file or Eloquent). The relationship-resolution path is the scaling question: rendering listings or index templates that pull related items across many entries risks N+1-style resolution. Load-test representative index pages before committing to wide use, and lean on Statamic's augmentation/caching rather than resolving relationships inside loops.

Failure modes to plan for:

• Silent authoring failure: CP field renders but sibling-reactive options stop updating after a Statamic minor — content gets saved with wrong or empty relationships, discovered much later. Highest-severity mode; mitigated only by manual QA.
• Template breakage: {{ fir }} output changes on upgrade — the new tests make this less likely, but their existence means the tag's behavior is now a maintained contract that can legitimately change at a major.
• Data-shape drift: mixed index/keyed array storage across fields makes templates branchy and future migration painful.
• Upgrade dead-end: falling behind on Statamic makes v1.4.1 the permanent ceiling for this addon, forcing an eventual build-your-own decision under time pressure.

Ramp-up: Authors need essentially no training — it behaves like a standard relationship field, and the sibling-reactivity fix makes it less surprising than before. Developer ramp-up is moderate: understanding the publish container model is necessary to debug field behavior and to judge whether a future Statamic release is safe. Realistic estimate: half a day for a developer already fluent in Statamic fieldtypes, one to two days for someone learning the CP internals. Compared with the alternative — building and maintaining an equivalent relationship fieldtype in-house — this remains the cheaper option, provided the team accepts the single-maintainer risk and funds the per-upgrade QA ritual.