Download the PHP package sushidev/fairu-statamic without Composer

This is the official Fairu addon for Statamic.

Fairu is your new powerful image and file proxy with the goal in mind to deliver your files in an optimized way.

[!WARNING] Upgrading from v2 to v3: Fairu is now gated behind dedicated permissions. After upgrading, grant the new Fairu Assets permissions in each role under Users → Roles — otherwise non-super users lose Fairu access (nav hidden, action endpoints return 403). Already-attached assets in fields still render for everyone; only interactive actions are gated.

Permissions (all under the Fairu Assets group): view, upload, edit, rename, move, delete fairu assets. Independent — view is required for anything that needs the folder picker (move, browsing in fields), so grant it alongside any other action.

Features

This addon provides:

• Import all your assets into fairu.app using our commands
• Antlers tags making image handling smooth sailing.
• Fieldset to easily embed Fairu hosted files into your new or existing project

How to use

You can install this addon via Composer:

Add env variables

Find your tenant ID in the tenant settings and create an API key for your application.

Import

On an existing project, you can run the following command which will automatically import all the connected assets into your fairu account. Depending on on the amount of files it might take some time.

After the initial import, file paths will be transformed into the new Fairu-ID format dynamically.

Antlers tags

There are several tags available to generate different code.

Metadata

[!NOTE] The tags generally don't fetch metadata from the Fairu server and build the file path locally. Use the fetchMeta parameter to fetch the asset information from Fairu.

You can fetch metadata by passing fetchMeta="true" to the tags, which makes the metadata accessible.

Lean vs. full fetch

The addon can fetch metadata in two modes:

The lean endpoint is ~8× smaller and issues 3–10× fewer SQL queries on the Fairu backend. Unless you need license/block data at render time, stick with the default.

Fields accessible via fetchMeta="true":

• name
• alt
• caption
• focal_point (x-y-zoom e.g. 40-30-1)
• focus_css (e.g. 40% 30%)
• width | height
• is_image | is_video | mime
• active

Use fetchMeta="full" when you additionally need description, copyrights, licenses, block, size, fingerprint, extension, or any other non-rendering metadata.

Automatic meta coalescing

When a page uses many {{ fairu:image }} / {{ fairu:url ... fetchMeta="true" }} tags — especially when they come from nested components, bards, or loops that you don't control up front — the addon automatically collapses every meta fetch on the page into a single batched API call.

How it works

1. Each tag emits an opaque placeholder token instead of immediately fetching meta.
2. A response middleware (CoalesceFairuMeta) queues all ids while the view renders.
3. After Antlers finishes, it fires one POST /api/files/meta call for every unique id across the whole response.
4. The placeholders are replaced in-place with the final <img> / URL output.

Result: a page with 15, 30, or 300 images issues exactly one meta round-trip per request, independent of template nesting.

Enabling / disabling

Enabled by default. Toggle via environment variable:

…or in config/statamic/fairu.php:

Caveats

• Do not wrap fairu tags in {{ cache }} blocks. The placeholder would get cached without the corresponding queue entry, so subsequent cache-hit renders can't resolve it. Use Statamic's response-level static caching instead — the middleware runs before static caching stores, so the cached HTML contains the final output.
• String operations on tag output (e.g. {{ fairu:url ... | upper }}) will operate on the placeholder, not the URL. Rare, but worth noting.
• Only text/html responses are rewritten. JSON, streamed, and binary responses pass through untouched.
• Tags without fetchMeta or with an explicit name parameter render immediately and don't go through the coalescer — no change in behaviour.

Requirements

The POST /api/files/meta endpoint is required on your Fairu backend for the default (lean) mode and for meta coalescing. It ships with fairu-app alongside this addon version. If you run an older Fairu deployment that doesn't expose the endpoint yet, set FAIRU_COALESCE_META=false and use fetchMeta="full" until the backend is updated.

Available parameters

Request a video rendition with version="medium":

The value is passed to the proxy as version=medium, including in generated srcset URLs. Available renditions depend on your Fairu proxy. raw="true" suppresses this parameter; fairu:url download="true" downloads the original.

{{ fairu }}

Get the file and get access to image properties.

{{ fairu:url }}

Get the URL of a file.

If you don't know the filename (e.g. for video files where the extension matters for browser playback), pass fetchMeta="true" to resolve the real filename from Fairu:

Raw originals (PDFs etc.)

By default the URL carries a transform query (?quality=90&focal=…) so images can be processed by the proxy. For files that must not be transformed — PDFs, ZIPs, original documents — pass raw="true" to get the untouched original:

raw works on every tag ({{ fairu }}, {{ fairu:image }}, {{ fairu:images }} too).

Forcing a download

Files are served inline by the CDN, so linking to them opens the file in a new tab. The HTML download attribute is ignored because the file lives on another origin. Pass download="true" to route the URL through a same-origin endpoint that streams the file with a Content-Disposition: attachment header, so the browser saves it:

Combine with fetchMeta="true" when you don't know the filename — the resolved name becomes the downloaded file's name.

download only works on {{ fairu:url }}. Unlike raw, it is ignored on {{ fairu }}, {{ fairu:image }}, and {{ fairu:images }} — those tags emit the CDN URL directly. To force a download, wrap a {{ fairu:url ... download="true" }} in your own <a> tag.

{{ fairu:image }}

Generate a complete HTML image tag.

{{ fairu:images }}

Generate multiple HTML image tags (see [[#{{ fairu image }}]])

Responsive Images

With most of our tags you have easy access to implementing responsive images using the native srcset and sizes properties to define when which source (version of the image) should be used. See the mdn documentation for a great introduction into implementing responsive images.

Implementation

The sources attribute provides a way to easily pass an array of widths, breakpoints and optionally heights to generate a srcset property that includes all listed sources.

This allows you to pass the sources property and use the calculated srcset property along with a fitting sizes to define which sources should be used when:

Formats

Each pair consists of:

• A width value (in pixels) that defines the image width at that breakpoint
• A height value (in pixels) that defines the image height at that breakpoint (optional)
• A breakpoint value (with 'w' suffix) that corresponds to the viewport width

Ratio

If all sources should have the same aspect ratio, you can use the ratio attribute as a shortcut without height:

This calculates all heights accordingly.

The sizes attribute

The ⁠sizes attribute tells the browser how large the image will be displayed at different viewport widths. If not provided, it will be auto-generated based on the breakpoints in the ⁠sources parameter.

For a full-width responsive image, you can leave the sizes property empty or you can use:

For more complex layouts, add media queries and a default or fallback value as last value:

Details

For more information, visit the documentation at https://docs.fairu.app/docs/addons/00-statamic to find out what else you can do with Fairu.