kraenkvisuell / statamic-bunny-cache
Full static caching for Statamic on the bunny.net CDN: pages are cached at the edge and purged through the bunny.net API whenever Statamic invalidates them. No nginx rewrite rules, no public/static folder.
Package info
github.com/kraenkvisuell/statamic-bunny-cache
Type:statamic-addon
pkg:composer/kraenkvisuell/statamic-bunny-cache
Requires
- php: ^8.3
- illuminate/support: ^12.0||^13.0
- statamic/cms: ^6.0
Requires (Dev)
- larastan/larastan: ^3.9
- laravel/pint: ^1.29
- orchestra/testbench: ^10.0||^11.0
- pestphp/pest: ^4.0
- pestphp/pest-plugin-laravel: ^4.0
- phpstan/extension-installer: ^1.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Full static caching for Statamic on the bunny.net CDN.
Instead of writing pages to public/static and serving them with nginx rewrite rules, the bunny strategy lets the bunny.net pull zone in front of your site be the static cache:
- Every page Statamic would cache goes out with
Cache-Control: public, max-age=0, s-maxage=…and aCDN-Tagheader, and without cookies. bunny.net keeps it at the edge; browsers always revalidate. - When Statamic invalidates pages (an editor saves an entry, a global, a nav, an asset…), the addon purges exactly what Statamic invalidates through the bunny.net API: single URLs, or all pages by their cache tag when the whole cache is cleared. Images, CSS and JS in the same pull zone stay cached.
{{ nocache }}regions and CSRF tokens work exactly like Statamic's full measure caching: the cached page contains placeholders, and a small script fetches the per-visitor parts from your server.- No nginx config, no
public/staticfolder, no files on the server.
All purges of one request, command or queued job are collected and sent once, after the response has gone out, so saving in the CP stays fast. This also works in apps upgraded from Laravel 10 that still have an app/Http/Kernel.php without Laravel's InvokeDeferredCallbacks middleware. A failing purge is logged and never breaks a save.
Requirements
- PHP 8.3+, Laravel 12 or 13, Statamic 6.0 or later
- A bunny.net pull zone in front of the whole site (the origin is your Laravel app)
Installation
composer require kraenkvisuell/statamic-bunny-cache
Add to .env:
STATAMIC_STATIC_CACHING_STRATEGY=bunny BUNNY_API_KEY=your-account-api-key BUNNY_PULL_ZONE_ID=1234567
BUNNY_API_KEY is the account API key (bunny.net dashboard → Account settings → API), not a storage zone password. Several pull zones (e.g. one per domain) can be given as BUNNY_PULL_ZONE_ID=1234567,1234568.
That's it: the bunny strategy registers itself, there is nothing to add to config/statamic/static_caching.php. Without the API key or zone ID, pages are still sent as cacheable, but nothing is purged (a warning is logged), so leave the strategy off locally.
Optional settings (publish the config with php artisan vendor:publish --tag=bunny-cache-config):
| Env | Default | |
|---|---|---|
BUNNY_CACHE_EDGE_TTL |
2592000 (30 days) |
How long bunny.net keeps a page. Purges make long values safe. |
BUNNY_CACHE_TAG |
statamic-page |
The CDN-Tag of all pages, used to purge only pages. |
BUNNY_CACHE_TIMEOUT |
10 |
Timeout of bunny.net API calls in seconds. |
Pull zone settings
Check them with:
php please bunny:check # report php please bunny:check --fix # also turns cookie stripping off
--fix only touches cookie stripping. Set everything else in the bunny.net dashboard under CDN → your pull zone → Caching:
Caching → General
| Setting | Value | Why |
|---|---|---|
| Smart Cache | off | Smart Cache never caches text/html, so it would never cache a page. With it off, bunny.net follows the Cache-Control header the addon sets. |
| Cache expiration time | Respect origin Cache-Control | The addon decides what is cached and for how long. With a fixed time, the edge also caches the CP, logins and other private responses. |
| Browser cache expiration time | Match server cache expiration (default) | bunny.net then passes the addon's header to browsers unchanged (max-age=0), so a purge reaches everyone at once, while assets keep their own browser cache time. The other options are fixed times for every file, pages included. |
| Query string sort | on (default) | Harmless; one cached copy per set of parameters. |
| Cache error response | off | Errors should never be cached, not even for 5 seconds. |
| Vary Cache | only URL Query String, and only if your site's config/statamic/static_caching.php has 'ignore_query_strings' => false (Statamic's default) |
Statamic caches /page?a=1 and /page as separate pages unless ignore_query_strings is true; bunny.net must do the same, or URL purges miss query string variants. With true, select nothing. Never select Cookie Value: that makes every visitor's copy separate. |
| Vary Cache by Request Headers | empty | |
| Strip response cookies | off | Otherwise bunny.net strips the session cookie from every response and nobody can log in to the CP. The addon already removes cookies from cached pages. |
| Optimize for large object delivery | off | Only for video and large downloads. |
| Stale Cache | While Origin Offline recommended | Keeps serving cached pages while your server is down. |
Caching → Perma-Cache
Off. bunny.net can't purge by tag with Perma-Cache.
Caching → Origin shield
On (recommended). Edge locations fetch from the shield instead of each asking your server to render the page, and static:warm fills the shield for all of them.
Caching → Request coalescing
Off. It merges simultaneous requests for an uncached URL into one, so two people loading the same CP page or other private response at the same moment could get each other's.
Deploying
Nothing to do in nginx: the default Laravel site config is all you need:
location / { try_files $uri $uri/ /index.php?$query_string; }
In the deploy script, after building the frontend:
php artisan config:cache php please static:clear # purges all pages at bunny.net (cached HTML points to the old CSS/JS) php please static:warm # optional: fills the cache again through bunny.net
Switching from Statamic's file cache
If the site used full measure caching (full strategy) before, three things:
- Delete
public/staticon the server once (rm -rf public/static). Thebunnystrategy never writes or deletes these files, andstatic:clearnow purges at bunny.net instead of deleting them. As long as the old nginx rules are in place, nginx keeps serving these stale pages from disk without asking PHP, so edits never show up and purges don't help. - Replace the
@staticrewrite rules (Forge's "Statamic" site template adds them:set $try_location @static;, the twoifblocks,location @staticandlocation @not_static) with the defaultlocation /block above. Without files inpublic/staticthey only fall through to PHP, but removing them makes sure no stale file is ever served again. - Purge the whole pull zone once after deploying:
php please bunny:purge --zone. bunny.net may still hold pages it cached before the switch (served by nginx frompublic/static, with bunny.net's default cache time). They have noCDN-Tag, so the tag purge after a save never removes them, and the home page in particular can stay stale for weeks. Browsers that got such a copy may keep it too (bunny.net sends them the same longmax-age), so check with a hard reload.
Commands
php please bunny:purge # purge all pages (by tag) php please bunny:purge https://example.com/about https://example.com/blog/* php please bunny:purge --zone # purge the whole pull zone, assets included php please bunny:check [--fix]
php please static:clear purges all pages too.
How it works
The bunny cacher extends Statamic's FileCacher, because Statamic adds the nocache and CSRF scripts only for file cachers, and then sends even the first visitor the same placeholder page as everybody else. That makes every response the cacher touches safe to share. The cacher never writes or reads a file:
- Caching a page records the URL in Statamic's URL list (so invalidation rules work as usual) and marks the response. Right before it is sent, the response gets the edge cache headers, loses its cookies, and its content becomes the version Statamic would have written to the cache file, with nocache and CSRF placeholders. (Since Statamic 6.3.2 Statamic sends that version to the first visitor anyway; before, the first visitor's own nocache regions and CSRF token were in it, and the addon takes care of that.)
- Serving a page never happens on the server: PHP renders every miss, bunny.net serves every hit.
- Invalidating a URL purges it (plus its query string variants Statamic knows about); wildcards become bunny.net prefix purges; flushing the cache purges the cache tag. "Refreshing" (background recache) purges as well, and the next visitor fills the edge.
Things to know
- Anything per visitor (forms with old input, a logged-in user's name, a cookie banner's state) must be inside
{{ nocache }}or@nocache, exactly like with Statamic's full measure caching. php artisan cache:clearalso deletes the nocache regions Statamic keeps in the cache. Runphp please static:clearafter it, so bunny.net doesn't serve pages whose regions are gone.- Leave
STATAMIC_BACKGROUND_RECACHEoff. It works, but brings nothing: there is no cached file to keep serving while a page re-renders, so "refreshing" a page just purges it like an invalidation does. Withrules: allit is worse: Statamic then refreshes the URLs in its own URL list one by one instead of flushing, so the addon purges URL by URL instead of by tag, and misses any page bunny.net holds that Statamic's list doesn't know about (e.g. aftercache:clear). - Purge rate limits: bunny.net allows about 300 URL and tag purges and 30 prefix or zone purges per minute per account. The addon retries when it gets a
429. - Editors see the cached pages like everybody else; Live Preview and draft, private or protected pages are never cached.
Support
Questions and bugs: GitHub issues. Please include your Statamic and Laravel versions and the output of php please bunny:check.
Changelog
See the GitHub releases.
Testing
composer test
License
MIT. See LICENSE.md.