Download the PHP package justinholtweb/craft-freelink without Composer

FreeLink for Craft CMS 5

A powerful, lightweight link field plugin for Craft CMS 5. Hybrid storage with proper element relations, 12 built-in link types, and migration paths from Hyper, Linkit, Typed Link Field, and native Craft Link fields.

Why FreeLink?

FreeLink takes a different approach to link fields:

• Hybrid storage — Simple links (URL, email, phone) are stored as JSON in the content column. Element links (entries, assets, etc.) get proper rows in a relations table with foreign keys. This gives you referential integrity and reverse lookups without a separate cache table.
• Lightweight models — Links extend yii\base\Model, not Craft's Element class. Less overhead, simpler API.
• Native CP UI — Field UI uses Craft's Garnish library and vanilla JS. No Vue.js, no Alpine.js.

Requirements

• Craft CMS 5.0.0+
• PHP 8.2+

Installation

Configuration

Add a FreeLink field in Settings > Fields. The settings UI lets you:

• Enable/disable individual link types and set custom labels
• Toggle between single-link and multi-link modes (with min/max constraints)
• Show/hide the link text field, new window toggle, and advanced attributes
• Set default link type and default new window behavior

Available Link Types

Twig Usage

Single-Link Mode

The field value is a LinkCollection that transparently proxies to the first link:

Multi-Link Mode

Element Resolution

Element links (entry, asset, category, user, product, variant) resolve their target element automatically when you access it — no .with() needed:

Note: Because the field value is a LinkCollection value object (not a raw element list), it does not participate in Craft's .with([...]) eager loading. Don't pass a FreeLink field handle to .with() — element links resolve lazily on access instead.

Reverse Lookups

Find elements that link to a given element:

Conditionals

GraphQL

FreeLink fields return [FreeLinkInterface] (always an array; single-link mode returns an array of one).

Element API

FreeLink works out of the box with craftcms/element-api. Link and LinkCollection implement JsonSerializable, so field values serialize to clean JSON objects with resolved URLs, display text, and element metadata.

Single-link fields produce a JSON object:

Element link fields include additional metadata:

Multi-link fields produce an array of objects.

You can also call toApiArray() directly on any link for programmatic use:

Custom Link Types

Register custom link types via the EVENT_REGISTER_LINK_TYPES event:

Your custom type should extend justinholtweb\freelink\base\Link (for simple links) or justinholtweb\freelink\base\ElementLink (for element links), and implement the displayName() and handle() static methods.

Migrating from Other Plugins

FreeLink includes console commands to migrate data from four popular link plugins. Each command converts the field type, transforms content data, and creates relations table rows for element links.

Options

Safety

• All migrators log each step to the freelink_migrations table
• --dry-run previews the entire migration without writing anything
• --backup uses Craft's built-in backup system before starting
• Migrate one field at a time with --field to reduce risk

Storage Architecture

Content Column (JSON)

Every link stores its metadata as JSON in the field's content column:

For element links, value is null in the JSON. The actual element reference lives in the relations table.

Relations Table (freelink_links)

Element link references are stored with proper foreign keys:

This means:

• Deleting a field or owner element automatically cleans up relations
• Deleting a target element sets targetId to null (the link gracefully becomes empty)
• Queries against the relations table use proper indexes and foreign keys

License

This plugin requires a commercial license purchasable through the Craft Plugin Store.