Fairu Statamic Laravel Package

Getting Started

fairu-statamic is a Statamic addon (the fairu namespace suggests a file/media management layer), so treat it as a CP-facing fieldtype + storage bridge rather than a standalone Laravel package. With 0 stars, 0 dependents and a single 2026-09-10 release, budget an hour to read the source before wiring it into anything client-facing.

Minimum steps:

composer require sushidev/fairu-statamic
php artisan vendor:publish --tag=fairu-statamic-config   # name will vary — list tags with --provider
php artisan migrate                                      # only if the addon ships tables
php artisan statamic:stache:clear && php artisan config:clear

Then verify registration, because a single missing service provider is the most common reason "nothing happens" with a low-traffic addon:

php artisan about                      # provider should appear in the booted list
php artisan list | grep -i fairu      # any artisan commands the addon exposes
ls config/ | grep -i fairu            # published config file name

Where to look first, in order:

1. composer.json — required statamic/cms and laravel/framework constraints. If it declares statamic/cms: ^4.0 only, you cannot use it on a Statamic 5 site without an alias hack.
2. src/ServiceProvider.php — what it binds, what it registers (fieldtypes, routes, tags, nav).
3. routes/cp.php — the control-panel endpoints; this tells you what the addon actually does.
4. src/Fieldtypes/ — the public surface you'll interact with in blueprints.
5. config/fairu.php — credentials, disk, endpoint, caching TTL.

First use case: add the fieldtype to one blueprint field on a staging environment, upload one file via the CP, and confirm the value round-trips into an entry's front-end output. Don't start with a bulk import.

Implementation Patterns

Blueprint-first integration. The realistic day-to-day pattern is replacing or supplementing Statamic's built-in assets field:

# resources/blueprints/collections/pages/page.yaml
handle: hero_image
field:
  type: fairu            # confirm the exact handle from src/Fieldtypes
  container: main        # if it wraps an asset container
  max_files: 1

Confirm the fieldtype handle by reading registerFieldtypes() — do not assume it matches the package name.

Antlers consumption. Statamic fieldtypes normally augment to an Asset or array of assets, so existing templates keep working:

{{ hero_image }}
  <img src="{{ url }}" alt="{{ alt }}" width="{{ width }}">
{{ /hero_image }}

If the addon returns a custom DTO instead, check src/Fieldtypes/*.php for augment() and write one small partial (partials/fairu-image.antlers.html) that all templates include, so a future package change is a one-file fix.

Programmatic access. Wrap the addon behind your own service rather than calling its facade from controllers and commands everywhere:

// app/Services/MediaService.php
final class MediaService
{
    public function __construct(private Fairu $fairu) {}

    public function upload(UploadedFile $file, string $folder = 'uploads'): string
    {
        return $this->fairu->upload($file, $folder)->id();
    }
}

That indirection is the main insurance policy on an unproven dependency: if you later swap to native Statamic assets or another addon, you change one class.

Storage abstraction. If Fairu stores to its own remote bucket, keep the Statamic asset container configured as well. Use Fairu for editorial uploads and the native container for anything your application generates (exports, PDFs, thumbnails). Mixing both in one container is where URL and Glide confusion starts.

Queue large work. Editorial single-file uploads are fine synchronously. Any bulk migration or batch tagging should go through a job with the addon's client injected, plus ->onQueue('media'), so a slow remote API doesn't hang the CP request.

Multi-site. Check whether the addon is localizable. If not, either mark the field as non-localizable in the blueprint (localizable: false) or store the asset ID in a shared global. Silently divergent per-site values are painful to debug later.

Testing. In your own test suite, fake the remote boundary rather than the fieldtype:

$this->mock(MediaService::class, fn ($m) => $m->shouldReceive('upload')->andReturn('fake-id'));

If the addon ships no fake of its own (likely at this maturity), your wrapper is what makes feature tests deterministic.

Gotchas and Tips

Pin the version and commit the lockfile. With one release and zero dependents, you are the QA. Use an exact constraint ("sushidev/fairu-statamic": "1.0.0"), not ^1.0, and review the diff on every update — there is no community pressure-testing patches.

Config cache is the usual culprit. After publishing config, php artisan config:clear on local and php artisan config:cache in deploy. Most "credentials ignored" reports on small addons are a stale cached config or a .env key not added to the deploy environment.

Statamic stache. Fieldtype and blueprint changes require php artisan statamic:stache:clear. If a new fieldtype doesn't appear in the blueprint editor, this is the first thing to try, before blaming the addon.

Provider autoloading. Statamic addons are discovered via composer.json extra.statamic.providers and extra.statamic.fieldtypes. If you've added the package but nothing registers, run composer dump-autoload and check that block exists — packages published by small teams occasionally omit it.

Remote URLs vs. Glide. If Fairu serves files from its own CDN, {{ glide:hero_image }} will not transform them unless the addon implements Asset-compatible URLs. Test one glide: call early; if it fails, serve raw URLs and do responsive images with plain <img srcset> from the addon's own transform method.

Permission and CP nav. Verify a non-super user can use the field: Statamic permissions are per-addon and often unregistered, which surfaces as a blank field for editors. Check src/Permissions/ or the permissions key in the service provider.

Failure modes are silent. Statamic addons commonly catch HTTP exceptions and return null, so a bad API key looks like "no image." Add a temporary Log::debug() in your MediaService and watch storage/logs/laravel.log on the first upload — do not rely on the CP UI to tell you what went wrong.

Debugging checklist when a field is empty: value actually saved (inspect the entry's markdown/YAML), fieldtype handle matches registration, API credentials resolve (config('fairu.*') in tinker), remote API reachable (curl the endpoint), and stache cleared.

Extension points to prefer. Events and the container binding are stable-ish; subclassing the fieldtype or reaching into src/ internals is not. If the addon emits no events, ask for them (or wrap the client yourself) rather than extending concrete classes — an update will break you.

Exit strategy. Given adoption risk, keep Fairu IDs in a plain text field rather than a proprietary composite type where possible, and write the migration to native assets before you need it. A one-file MediaService plus a thin Antlers partial means swapping providers is a day's work instead of a rewrite.