Statamic Imageboss Laravel Package

Getting Started

ImageBoss is an image CDN/processing service; this addon wires Statamic assets into it so your templates emit CDN URLs instead of generating Glide derivatives on your own server. The 0.4.0 line is the first one worth adopting broadly, but it raises the floor.

1. Check the platform floor first. 0.4.0 requires PHP 8.3+, Laravel 12+, and Statamic 5–6. Laravel 11 and PHP 8.2 were explicitly dropped, so on an older app Composer will silently resolve you back to 0.3.x — pin your constraint deliberately rather than discovering the downgrade in production.
2. composer require jorisnoo/statamic-imageboss
3. Publish the addon config (Statamic addons land in config/statamic/) and set the ImageBoss token and source/bucket name via env. Note the 0.4.0 rename: what was previously secret is now token. Update both the published config and any .env keys, and search your deployment secrets for the old name — a stale value won't error, it will just produce unsigned URLs.
4. Where to look first: the published config (defaults for focal point and animation behaviour), the ImageBossBuilder class in src/ (the URL-building seam), and the Pest test suite, which is the most precise documentation of the expected URL shape.
5. First use case: a listing page of news cards or products. Swap asset-field output for the addon's tag/modifier with explicit width/height and compare against your current Glide output. This is the highest-volume, lowest-risk surface and immediately offloads resize work from your app servers.

Implementation Patterns

Define presets in config, not templates. The common failure mode with image CDNs is scattering width="600" height="400" across forty Antlers files. Name your sizes once (card, hero, thumb) in the addon config and reference the preset from templates. When design changes a ratio, you edit one file and the purge story stays simple.

Treat focal points as content, not code. 0.4.0 defaults focal points to center. That's a sane fallback, but for portrait and product photography a center crop frequently decapitates the subject. Statamic's per-asset focal point field is the right lever — brief editors to set it on hero imagery rather than hardcoding crop offsets in templates.

Let animation pass through. The new animation support matters for GIF/WebP assets that would otherwise be flattened to a single frame by an aggressive transform. Keep animated assets on a preset that doesn't force a static format, and confirm the output actually animates rather than trusting the flag.

Lean on automatic purge-on-reupload, but verify its edges. 0.4.0 purges ImageBoss cache when an asset is reuploaded. That covers the editor workflow (replace the photo, see the new photo). It does not necessarily cover assets replaced via the API, moved between containers, or reimported by a sync job. For those paths, trigger a purge explicitly in your own asset-saved listener.

Keep signing server-side. The token signs URLs; never expose it to the frontend. Generate URLs through the addon so signature parameters are always present and correctly ordered.

Make local dev explicit. Either point local at a separate ImageBoss source, or short-circuit to Glide in local so you don't burn quota and can develop offline. A config-driven switch beats a if (app()->isLocal()) scattered through templates.

Don't forget the plumbing. Add the ImageBoss host to your img-src CSP directive, and emit srcset/sizes from your presets so you get the responsive payoff rather than a single oversized CDN hit.

Gotchas and Tips

• The secret → token rename is the upgrade trap. It's a config/env key rename with no runtime warning. Signed-URL enforcement will start rejecting requests, or signatures will be omitted entirely, and the failure looks like a CDN problem rather than a config problem. Grep your repo, your .env.example, and your secret manager.
• Version resolution on older apps. Because Laravel 11 and PHP 8.2 support were dropped, composer update on a legacy app quietly keeps you on 0.3.x. Check composer show jorisnoo/statamic-imageboss after updating and confirm you got the version you think you did.
• Cache purges cost requests. Every reupload now fires a purge, and animated assets multiply the frames ImageBoss renders. Watch your usage dashboard for the first weeks after rollout, particularly if you have an import or migration that rewrites many assets at once.
• Debugging a broken image: take the generated URL, strip the query string, and confirm the source is reachable; then re-add parameters one at a time. Most failures are (a) missing/invalid token, (b) wrong source name, or (c) a parameter the source doesn't support — not the addon itself.
• ImageBossBuilder is your extension point. The 0.4.0 test refactor extracts mock helpers around this class, which signals it's the intended seam. If you need custom URL composition (signed URLs for a non-Statamic source, custom query params), extend there rather than concatenating strings in Antlers.
• Run the addon's own tests when you upgrade. The suite moved to Pest v4 and expanded significantly. It's fast, self-contained, and will tell you quickly whether your installed version behaves as the changelog claims.
• Pin and stage. This is a pre-1.0 package with a breaking config rename already behind it. Use a caret constraint on the minor, and roll it out behind a feature flag or on a single template before switching all image output.