Statamic Link It Laravel Package

Getting Started

Install and register

composer require rias/statamic-link-it
php artisan vendor:publish --tag=statamic-link-it-config   # if the package ships config/views

Statamic addons auto-register via package discovery, so there is no manual config/app.php step. Verify the addon loaded with php artisan statamic:addons (or check the Addons list in the CP) before debugging anything else — a silent discovery failure looks identical to a broken fieldtype.

Where to look first

1. README.md — for a package this small, the README is the specification. Read it end-to-end before writing a fieldset; the value shape it documents is the contract everything else depends on.
2. src/Fieldtypes/ — the PHP class gives you the authoritative answer on augment(), preProcess(), and what the stored payload actually looks like.
3. resources/js/ — the Vue component shows which options the editor UI exposes and what it writes back to the content file.
4. config/statamic-link-it.php (if published) — usually where link types (entry, asset, external URL, mailto, tel) are toggled and where icon sets or default targets are configured.

First use case

The canonical job is replacing a bare text field used for URLs in a hero/banner/CTA set. Editors currently type https://... by hand and you get broken links when content moves. Swap it for the link fieldtype so the editor picks an Entry, an Asset, or pastes an external URL, and the fieldtype resolves the right href at render time:

# resources/fieldsets/hero.yaml
title: Hero
fields:
  -
    handle: cta
    field:
      type: link_it          # confirm the exact handle in the README
      display: Call to action
      required: true

Then in Antlers:

{{ if cta }}
  <a href="{{ cta }}" >{{ cta:label ?? 'Read more' }}</a>
{{ /if }}

Start with a single field on a single entry type. Do not convert existing URL fields across the whole site until you have seen one rendered value — see the backfill note below.

Implementation Patterns

Keep a single render partial. Every call site will want the same href / target / rel / label logic. Put it in resources/views/partials/link.antlers.html and include it with the field as a scoped variable:

{{ partial:link :link="cta" fallback_label="Read more" }}

Inside the partial, guard the empty case once and you never repeat the <a> boilerplate (or forget rel="noopener"). Blade-heavy projects should do the same via a small <x-link> component that accepts the augmented array.

Treat internal links as references, not URLs. The value of this package over a plain text field is that an entry link stays correct when the entry's slug changes. That only holds if you render the resolved URL and never write the URL back into the field. If you find yourself copying {{ cta }} into a second plain-text field "for the sitemap", you have re-introduced the drift this addon exists to prevent.

Expose link types deliberately. If the config lets you enable link types, cut the list down to what your content model actually supports. Exposing mailto, tel, asset, entry, and url on every field is how you end up with editors using an external URL to point at their own site. Field-level config (per-fieldset overrides) is preferable to one global setting.

API and GraphQL surfaces. Augmented values generally serialize as the resolved href in Antlers/Blade but may return the raw stored array through toAugmentedArray() or REST. If you consume the field in a Nuxt/Inertia front end, decide early whether you ship the resolved URL or the reference + type, and normalize in one place (an API resource or a transformer) rather than in each client.

Validation. For front-end forms or imports, validate the field as a URL only after augmentation. Validating the raw value rejects entry references, which are usually IDs or paths, not https:// strings.

Migration path from a legacy field. Run a one-off command that reads the old text field, writes { type: url, url: $oldValue } (or whatever the README documents) into the new field, then flips the fieldset. Keep the old field in the blueprint, hidden, for a release cycle so you can roll back without a database restore.

Gotchas and Tips

The stored value is not a string. This is the single most common failure: developers write href="{{ link }}" because it works on external URLs, then discover entry links render as an ID, an array, or nothing. Dump the augmented value once at the start of the project — {{ cta | dump }} in Antlers, or {{ dd($entry->cta) }} via a route — and build your partial against that shape, not against the README's prose.

Adoption and maintenance risk is the real headline. Ten stars and zero dependents on the package index means essentially no field-hardening from third parties. Pin the version in composer.json ("rias/statamic-link-it": "1.0.*"), and if the project is long-lived or client-owned, budget for vendoring the fieldtype into addons/ or forking it. A link fieldtype is small enough to own — the alternative is that a Statamic major upgrade breaks a fieldtype you cannot patch. Note also the release date on the package page is ahead of the current date; confirm the tagged version actually installs against your Statamic major before committing to it.

Deleted or unpublished targets. Resolving an entry reference at render time means the href can vanish. Decide the policy — hide the whole CTA, fall back to #, or log — and implement it in the partial, not per template. The same applies to assets deleted from a container.

Static caching. If you use Statamic's static cache, entry references resolve at cache-warm time, which is normally correct: republishing the target entry should invalidate the URL's page only if the addon hooks the entry's save event. Test it — change a target entry's slug and check whether the referring page's static HTML updates. If it does not, either add the invalidation listener yourself or avoid static caching on pages that render cross-entry links.

External URL hygiene. Strip/normalize the scheme on save or your editor will produce https://https://.... Add rel="noopener noreferrer" whenever target="_blank" is set, and make that decision in the partial so a per-field "open in new tab" checkbox can't leak an unsafe link.

Config quirks. If the config file is publishable but not published, edits to config/statamic-link-it.php in your app will be ignored — the package's own copy is used. Publish it, then clear php artisan config:clear; cached config in production is a frequent reason a settings change "doesn't do anything".

Extension points worth knowing. The fieldtype's Vue component is the place to add a link type or a default label, and the PHP fieldtype's augmentation methods are the place to change how a stored reference resolves. Both are small files — read them before assuming you need a workaround at the template layer.