Statamic External Link Laravel Package

Getting Started

This is a small, single-purpose addon: it lets Statamic's Link fieldtype point at an external URL instead of only internal entries/assets. Treat it as a fieldtype extension rather than a framework — there is very little surface area to learn.

Install

composer require jonassiewertsen/statamic-external-link

v1.9.0 is the compatibility release for Statamic 5 / Laravel 11, which in practice means PHP 8.2+. If you are still on Statamic 4, pin ^1.8; if you are mid-upgrade, do the Statamic major bump first and add this package afterwards so Composer resolves a single coherent set of constraints.

Where to look first

1. composer show jonassiewertsen/statamic-external-link — confirm the installed version matches your Statamic major.
2. Your existing blueprint that uses the link fieldtype (usually a nav or links fieldset) — the addon's value shows up there, not in a separate control panel screen.
3. The addon's src/ directory — it is small enough to read end-to-end in a few minutes, which is the fastest way to understand exactly what it augments.

First use case

Add the field to a navigation blueprint, create a nav item in the CP, choose the external option, and paste a full URL. Then render it in your Antlers layout with an explicit target/rel so off-site links behave correctly:

{{ nav:main }}
  <a href="{{ url }}"{{ if external }} target="_blank" rel="noopener noreferrer"{{ /if }}>{{ title }}</a>
{{ /nav:main }}

That is the whole workflow: field in the blueprint, value in the CP, URL in the template.

Implementation Patterns

Blueprint-level configuration. The addon extends the Link fieldtype, so all of its behaviour is configured where the field is declared. Keep external-link fields in a dedicated fieldset (e.g. fieldsets/links.yaml) and reuse it across navs, footers, and CTA blocks — you get consistent CP behaviour for free and only one place to change when you upgrade.

Pair it with a navigation, not a page field. The natural fit is nav/links style structures where editors mix internal pages and off-site destinations. If you only ever need one external URL on a page, a plain text field plus a url validator is less machinery.

Normalise at render time, not author time. Editors paste example.com, https://example.com, and https://example.com/ interchangeably. Rather than fighting the CP, wrap rendering in a small partial or a computed value that ensures a scheme and strips duplicate trailing slashes:

{{ partial:link url="{{ url }}" label="{{ title }}" external="{{ external }}" }}

One partial means the target="_blank" rel="noopener noreferrer" decision lives in exactly one file, and you can audit it before a security review.

GraphQL / REST consumers. If the field is exposed via the REST or GraphQL API, keep the shape stable by mapping it into your own transformer rather than letting clients consume the raw augmented value — the raw shape is the addon's, and you do not want your front end coupled to it across a major bump.

Multi-site. External URLs are usually locale-independent, but the label is not. Store the label per-site (Statamic does this by default for nav titles) and leave the URL shared; it avoids re-entering the same URL three times.

Gotchas and Tips

The v1.9.0 bump is a compatibility release, not a feature release. The only changes are Statamic 5 and Laravel 11 support. That has two practical consequences: (a) there is no new behaviour to learn, and (b) the risk is in the environment, not the addon. Run composer update jonassiewertsen/statamic-external-link -W and then exercise a real nav in the CP — a Link fieldtype that silently renders empty after a Statamic major is the classic failure mode.

PHP 8.2 is the hidden constraint. Laravel 11 requires PHP 8.2+, so on shared hosting or a legacy CI image the upgrade will fail on the platform requirement rather than on the package. Check php -v in CI and in the deploy target before you touch composer.json.

Version pinning across a Statamic upgrade. Constrain to ^1.9 once you are on Statamic 5, and do not assume ^1.8 will float forward — old minors carry the old Statamic constraint and Composer will hold your whole upgrade back. If composer why-not statamic/cms 5.x points here, this is the reason.

target="_blank" without rel="noopener" is a real (if minor) security issue. Older browsers expose window.opener; modern ones imply noopener, but you should not rely on that for a public-facing site. Always emit both, as in the partial above.

Do not trust the URL blindly. An external link field is an editor-controlled href, which is an XSS vector if it ever accepts javascript:. Statamic escapes attribute output by default, which mitigates the common case, but if you build URLs in PHP before passing them to the template, validate the scheme against an allowlist (http, https, and your own protocols if needed).

Debugging an empty render. If the link renders blank, check in this order: (1) the blueprint actually uses the link fieldtype, not text; (2) the entry/nav item was re-saved after the addon was installed — augmented values are not always rebuilt automatically, so php please stache:warm or a re-save fixes most cases; (3) php artisan view:clear if you cached compiled Antlers.

Extension points. Because the addon is thin, resist forking it for small tweaks. Anything presentational belongs in your own partial; anything structural (extra validation, URL normalisation) belongs in a computed value or a small service class in your app. Fork only if you need a Statamic major the maintainer has not shipped yet — and if you do, expect to re-apply the patch on every release, since releases here are infrequent and mostly compatibility-driven.