Statamic Bunny Stream Laravel Package

Getting Started

This addon adds focal-point picking and focal-point-aware image rendering to Statamic assets. It targets Statamic 5 and 6; 1.1.2 is a control-panel-only fix, so nothing in your config or templates changes on upgrade.

1. composer require the package and run php please vendor:publish --tag=<addon>-config (and the assets tag if you want the CP bundle served from public/vendor) — then php please cache:clear.
2. Look first at the asset container config (config/statamic/assets.php or the container's YAML) to confirm the focal point field is enabled on the containers you care about. That is the single switch that decides whether editors see the picker.
3. Confirm the fieldtype/CP asset is registered by opening any asset in the control panel — you should see the focal point picker on the image preview.
4. First use case: pick a focal point on a hero image, then render it through Glide with a crop that respects the point rather than a hard-coded centre crop.

Start by reading the addon's service provider (what it extends/registers) and its fieldtype JS. Those two files tell you more about real behaviour than the README, especially for how the point is persisted onto the asset.

Implementation Patterns

Focal point as asset metadata. The point is stored on the asset's data (YAML/JSON alongside the file), not in a separate table. That means it travels with content exports, is editable in version control, and is available anywhere you can resolve an asset — templates, Antlers, Blade, and PHP.

Rendering pattern. Resolve the asset, read its focal point, and pass it into the image manipulation so the crop is anchored correctly. Wrap this in a single partial/component (resources/views/partials/img.htaccess-style helper or a Blade component) so every image on the site uses the same logic. Doing it ad hoc per template is how sites end up with half their images centre-cropped again.

Per-context overrides. A common need is "use the focal point, except on this card where I want a top-left crop." Design your helper to accept an optional explicit focus argument that wins over the stored point, rather than baking the stored value in globally.

Responsive sets. Generate srcset widths from one focal-point-aware transform definition so all sizes share the same anchor. If each width re-derives the crop independently you get visible jumping as the browser swaps sources.

Programmatic writes. For bulk imports (migrating from another CMS, or auto-detecting focus with a face/subject detector), write the point through the asset's data API rather than editing YAML by hand, then save the asset so caches and the Strapi-style index invalidate properly. This is the highest-leverage integration point: a one-off command that derives focal points beats hundreds of editor clicks.

Multi-site. Focal points are usually origin-shared, but confirm per-site localisation behaviour before promising editors that a per-site crop is possible. If the value is origin-only, treat it as a global decision in your content model.

Gotchas and Tips

• 1.1.2 specifically changes CP bundle scoping. The fix isolates the control-panel bundle from browser globals. If you previously worked around Statamic 6 preview breakage (patched vendor JS, reordered CP scripts in a CP customisation, or published an older bundle into public/vendor), remove that workaround — leaving it in place can double-load the bundle and reintroduce the conflict.
• Republish or hard-refresh after upgrading. php please vendor:publish --tag=<addon>-assets --force if you serve assets from public/vendor, and have editors hard-reload the CP. A stale cached bundle will look exactly like the bug the release just fixed.
• Statamic 5 is untouched. Don't roll a "verify 5 still works" regression pass beyond a smoke test; the release explicitly preserves 5 behaviour. Conversely, don't assume your 5-era CP customisations apply to 6 — the bundle isolation is a 6-only concern.
• Global collisions are the failure mode to watch for. Any other addon or your own CP JS that defines a broad global can shadow the focal point code. If previews break again after a future upgrade, check the browser console for duplicate/overwritten globals before assuming the addon is at fault.
• Glide cache invalidation. Changing a focal point updates asset data, but already-generated Glide images may still be served from storage/statamic/glide. When testing a changed focal point, bust the cache (php please glide:clear) or you'll conclude the addon is ignoring your change.
• Only focal-point-aware manipulations respect the point. Anything that resizes without a crop/focus parameter behaves as before. If a template "ignores" the focal point, check the transform arguments first — it's almost never a data problem.
• Debugging order: asset data has the point? → container has the field enabled? → template passes the point into the transform? → Glide cache cleared? That sequence resolves nearly every report.
• Extension points: the fieldtype and the transform/URL building are the two places to hook. Prefer composing your own helper around the addon over subclassing the fieldtype — CP internals are the part most likely to change between Statamic majors, as 1.1.2 demonstrates.