Statamic Splash Laravel Package

Getting Started

• Install with Composer: composer require aryehraber/statamic-splash. Statamic auto-discovers the addon via its service provider — no manual registration in config/app.php.
• Create an Unsplash developer app at unsplash.com/developers and grab the Access Key (not the secret). The free “Demo” tier is limited to ~50 requests/hour; request production access for real work.
• Publish the addon config (tag name varies by version — check the package README or run php artisan vendor:publish and pick the Splash provider), then put credentials in .env:

  UNSPLASH_ACCESS_KEY=your_access_key
  

• Clear caches after install/config changes: php artisan config:clear && php artisan statamic:stache:clear.
• Look first at these files in vendor/aryehraber/statamic-splash/:
  • config/splash.php (or similar) — API key, default asset container, image size/quality options
  • src/ServiceProvider.php — what gets registered (fieldtype, CP nav, routes)
  • src/Fieldtypes/ — how the CP picker is wired to Statamic
  • resources/js/ — the Vue component behind the CP UI
• First use case: add the Splash field to a blueprint (e.g. a hero_image field on a Page collection) and pick an Unsplash photo directly from the publish form. Alternatively, use the CP nav entry to browse and import into an asset container, then reference the resulting asset normally.

Implementation Patterns

Blueprint field pattern (most common). Add the addon’s fieldtype handle to a blueprint YAML:

fields:
  hero_image:
    type: splash        # verify exact handle in the addon's fieldtype class
    display: Hero Image
    container: assets   # target asset container for the imported file

The field stores the imported asset reference, so your Antlers/Blade templates treat it like any other asset:

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

Import-into-container workflow. Configure a default asset container so picked photos land somewhere predictable (assets/images/unsplash/…). This keeps the asset browser consistent and means the CP selection survives if the Unsplash API is down later — you own a local copy.

Search-then-download pattern. Use the CP browser for discovery, but drive the actual download through Unsplash’s links.download_location trigger if you’re building programmatic imports. Skipping that endpoint is a terms-of-service violation, not just a nicety.

Programmatic access. If the addon exposes a service/API wrapper, inject it rather than calling Unsplash directly, so caching and credentials stay in one place:

public function __construct(private Splash $splash) {}

public function photos(string $query): array
{
    return Cache::remember("splash:{$query}", now()->addHour(), fn () => $this->splash->search($query));
}

Cache aggressively — search results don’t change minute-to-minute, and you’ll burn the demo quota fast otherwise.

Editor workflow. For content teams, pair Splash with a normal asset field: Splash for initial selection, then editors can swap the asset later without re-hitting the API. Document this in your editor guide so people don’t assume every image must come from Unsplash.

Multi-site. Imported assets live in the container, so they’re shared across sites by default. If you need per-site hero images, keep the Splash field inside a localized fieldset or use site-specific fields rather than one global picker.

Extension points. Rather than forking, extend via:

• A custom fieldtype that wraps Splash and adds validation (e.g. min width, aspect ratio).
• Config overrides for container, folder, and image transform parameters.
• A small Artisan command that pre-warms a curated set of images so editors aren’t waiting on the API during busy periods.

Gotchas and Tips

• API quota is the #1 failure mode. Demo apps allow ~50 req/hour. Symptoms are silent empty results or 403s in the CP. Request production access, and cache search responses. Add a clear error state in the CP if you fork the component.
• Attribution is required by Unsplash. You must credit the photographer and link back. If the addon imports the asset without metadata, store photographer_name and photographer_url alongside it (often as asset meta or a separate field) and render attribution near the image.
• Use the download trigger. Unsplash’s guidelines require hitting the photo’s download_location when a user “downloads” an image. A raw images.unsplash.com fetch into your container technically doesn’t count. Check whether the addon does this; if not, add it in your own import path.
• Don’t commit the access key. Config files often read env('UNSPLASH_ACCESS_KEY') — keep it that way, and remember php artisan config:cache in production means env changes require a re-cache.
• Statamic stache and assets. After importing, the asset container index may not refresh immediately. If new files don’t appear in the CP, run php artisan statamic:stache:clear (or stache:warm).
• Version compatibility. This is a small, low-star package (13 stars, last release 2026-08-30). Pin the version in composer.json and check the README for the supported Statamic major (v3/v4/v5 fieldtype APIs differ). Test upgrades in a staging branch.
• Network timeouts block the CP. A slow Unsplash response can hang the publish form. If you control the field component, set a client-side timeout and fail gracefully; otherwise keep an eye on this in editor reports.
• Duplicate imports. Repeated picks can create image-1.jpg, image-2.jpg clutter. Standardize the destination folder and consider a deterministic filename based on the Unsplash photo ID if you customize the import.
• Permissions. Decide which roles can browse Unsplash — uncontrolled image imports can bloat storage. Gate the CP nav/field via Statamic permissions if the addon doesn’t.
• Debugging tips. Watch storage/logs/laravel.log for API errors; use php artisan tinker to hit the addon’s service directly and isolate whether a failure is API-side or fieldtype-side; inspect the network tab in the CP to see the actual Unsplash request and response code.
• Vendor publish collisions. If you’ve already published a config under the same tag, vendor:publish won’t overwrite. Use --force deliberately and diff first.
• License note. The addon is MIT, but Unsplash’s API terms are separate and stricter — don’t conflate the two when doing a compliance review.