Statamic Element Picker Laravel Package

Getting Started

• Know which major you're on. v1.1.0 adds Statamic 5 support; v1.0.x is the Statamic 4 line. Statamic 5 pulls in Laravel 11 and requires PHP 8.2+, so confirm your app meets that before upgrading. If you're still on Statamic 4, stay pinned to ^1.0.
• Install: composer require eminos/statamic-element-picker — Statamic addons are auto-discovered, so there is usually no manual provider registration. Run php artisan vendor:publish --tag=statamic-element-picker (or check the README for the exact tag) if the addon ships a publishable config.
• Look first at: the addon's config/ file (or README config block) to see where "elements" are defined, then the fieldtype's source in src/Fieldtypes/ if you need to extend it.
• First use case: open CP → Blueprints → [your collection], add a field of type Element Picker, point it at your element source, and save. Then add the field to a page and confirm the picker renders and persists a value. That round-trip tells you more about the addon than any docs.

Implementation Patterns

• Blueprint-first configuration. Keep all per-field behaviour (single vs. multiple selection, which element set, any display options) in the blueprint/config, not in templates. That way content editors change behaviour without a deploy.
• Render through a partial. Rather than inlining element markup in every template, resolve the picked value and pass it to one Antlers partial/component that owns the markup for each element. It keeps the picker's output swappable.
• Store handles, resolve at render. The picker typically persists an identifier (handle/slug) rather than a full object. Treat the stored value as a reference and look up the element at render time so label/markup changes propagate to existing content.
• Multiple selection: expect an array-shaped value; guard with {{ if field }} and loop, since an empty picker usually yields null/[] rather than a consistently empty array.
• Reuse across collections and globals. Because it's a fieldtype, the same field can be added to any blueprint, including Globals and Taxonomies — good for site-wide "featured element" settings.
• API/GraphQL exposure comes for free via Statamic's augmentation; if you need a richer payload than the raw handle, add an augmenter or a computed value rather than reshaping in the template.
• Pin the constraint in composer.json (^1.1 for Statamic 5) so a future major doesn't silently land during an unrelated composer update.

Gotchas and Tips

• The v1.0 → v1.1 jump is a compatibility boundary, not a feature one. Nothing in the release notes suggests breaking API changes, but the supported Statamic major changed. Run composer why-not eminos/statamic-element-picker ^1.1 before upgrading — it pinpoints which dependency (usually statamic/cms) is blocking you.
• Blueprint field handle renames are data migrations. Renaming the field handle in a blueprint orphans existing values. Add the new field, copy data, then remove the old one.
• Cache after config changes. Editing the addon config or blueprints can require php artisan cache:clear and php artisan statamic:stache:clear before the CP reflects the change.
• Empty != missing. In Antlers, a cleared picker may augment to null while a misconfigured one returns false or an empty string. Log the raw value once in dd()/ray() during setup so your conditionals test the right thing.
• Missing elements fail silently. If an element is removed from the source config but still referenced in content, rendering typically degrades quietly. Add a defensive check in your partial and render nothing (or a fallback) when resolution returns empty.
• Extension points: prefer a custom view/partial for markup overrides and Statamic's augmenter API for value shaping; avoid editing files under vendor/, since a composer update will wipe them.
• Test the CP, not just the front end. A picker that renders fine on the front end can still be broken in the publish form (e.g. after a Statamic 5 upgrade). Load an entry in the CP once after upgrading.