Statamic Field Item Relationship Laravel Package

Getting Started

• Install: composer require eminos/statamic-field-item-relationship:^2.0. This is a Statamic addon, so there is no service provider to register — Statamic's addon autoloading picks it up and the fieldtype/tag appear automatically.
• Version gate first: v2.0 targets Statamic 6 (Vue 3 control panel). If you are still on Statamic 5 or earlier, stay pinned to ^1.4 and treat this release as unavailable to you. Decide this before you touch any blueprint.
• Look here first: the README for blueprint YAML examples, then src/Fieldtypes/ (the fieldtype config and its preProcess/preload behaviour) and src/Tags/ (the {{ fir }} tag). The Pest suite added in v2.0 is the most honest documentation of tag output — read the tests for {{ fir }} before you guess at a rendering problem.
• First use case: add the field to a blueprint, point it at a source field/set of items, save an entry, then render it in a template with {{ fir }}. That end-to-end loop — blueprint → CP field → Antlers/Blade tag — is the whole package; once it works, the rest is configuration.

Implementation Patterns

• Configure in the blueprint, not in code. The fieldtype's behaviour (which items are selectable, what gets stored) is blueprint config. Keep it in the YAML so it travels with the fieldset and is diffable in review rather than living in a panel-only setting.
• "Save as: Index" for simple string arrays. New in v2.0. When your source is a plain array of strings, you can now store the array index instead of the string. Use this when labels are editorial and may be reworded later — the stored value survives copy edits because it references position, not text. Use Save as value when the stored string is consumed by code (URLs, handles, keys) and must be self-describing.
• Reactive sibling fields. The v2.0 fix means a FIR field now participates correctly in conditional/field-dependency logic: the CP reads the publish container's values directly instead of scraping the DOM. If you have fieldsets with if: conditions keyed off a FIR field, that visibility now tracks live edits in the publish form. Lean on this instead of hiding fields with custom JS.
• Render through the tag, keep markup in your templates. Treat {{ fir }} as the single access point and style/loop around it — that keeps you free to change the target field later without touching every template. Wrap in {{ if fir }} for optional fields so an unset selection renders nothing rather than an empty block.
• Blade vs Antlers: if the rest of the project is Blade components, wrap the tag in one component (<x-field-item :field="$entry->thing" />) so the Antlers call site is isolated to one file.
• Test your own usage with Pest. The added {{ fir }} test suite means the tag's contract is now pinned; mirror that by writing feature tests that render your actual templates. That is the cheapest regression net for an addon whose output depends on blueprint config you also control.
• Pair with caching carefully. Because the rendered value depends on both the relationship field and the target field, cache invalidation should key on the entry holding the field — not on the target entry's URL or ID.

Gotchas and Tips

• This is a major bump, not a patch. The headline change is Statamic 6 / Vue 3 support; it is safe to assume Statamic 4–5 is unsupported on ^2.0. Plan the addon upgrade as part of the Statamic 6 migration, not as an independent composer update.
• Custom CP JavaScript that targeted the old DOM will break. v2.0 replaced "fragile DOM/component lookup" with publish-container values. Any of your own control-panel JS or Alpine hacks that hooked the old element structure or listened for the previous reactive behaviour needs to be re-pointed at the publish container or deleted.
• "Save as: Index" silently degrades if the array is reordered. Storing an index is only stable while the source array's order is stable. Reordering the option array remaps every existing value. If your source list churns, prefer value-based saving and accept label drift.
• Re-publish overridden views if you had any. If you previously published the addon's views to customise tag markup, re-publish (--force) into a clean diff before upgrading — a Vue 3-era release is a plausible time for template churn.
• Clear caches after blueprint edits. Stache and view caches will happily serve a stale fieldtype config or a rendered tag output; php artisan statamic:stache:clear plus your view/response cache is step one of any "the tag renders nothing" debug session.
• A blank {{ fir }} is usually a config problem, not a tag problem. Check, in order: the field has a saved value; the target field still exists under that handle (renames don't migrate stored data); the blueprint field is scoped to the right container/collection; and the entry is published in the current site. Multi-site installs should verify localisation of the target field, not just the relationship field.
• Extension points: fieldtype preProcess/preload for shaping what the CP receives, and the tag (now under test) as the stable public surface — prefer overriding tag output via a published view over patching src/.
• Version pin discipline: in composer.json use "eminos/statamic-field-item-relationship": "^2.0" for Statamic 6 projects and "^1.4" for anything older, and note the choice in your upgrade runbook — this is exactly the kind of addon that gets dragged into an unintended major by a loose constraint.