jorisnoo / statamic-bunny-purge
Automatically purge Bunny CDN cache when Statamic content changes.
Fund package maintenance!
Requires
- php: ^8.3
- illuminate/contracts: ^12.0||^13.0
- spatie/laravel-package-tools: ^1.16
- statamic/cms: ^5.0 || ^6.0
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.8
- orchestra/testbench: ^10.0||^11.0
- pestphp/pest: ^3.0||^4.0
- pestphp/pest-plugin-arch: ^3.0||^4.0
- pestphp/pest-plugin-laravel: ^3.0||^4.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- spatie/laravel-ray: ^1.35
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Automatically purge your CDN cache when Statamic content changes. Works with Bunny CDN out of the box, but supports any CDN with a purge API.
Installation
You can install the package via composer:
composer require jorisnoo/statamic-bunny-purge
Add your API key to .env:
CDN_PURGE_API_KEY=your-bunny-api-key
Bunny is the default endpoint. Content saves require a Statamic static caching strategy and invalidation rules; without a strategy, Statamic does not run its content invalidator. To purge public assets, set CDN_PURGE_ASSET_CONTAINERS=assets,downloads to the container handles you serve through the CDN. Run a persistent queue worker for retries and pacing.
Configuration
You can publish the config file with:
php artisan vendor:publish --tag="bunny-purge"
The published file reads the following settings (for example, api_url reads CDN_PURGE_API_URL):
| Key | Description | Default |
|---|---|---|
api_url |
The CDN purge API endpoint | https://api.bunny.net/purge |
api_key |
Your CDN API key | — |
auth_type |
Auth header style: access_key or bearer |
access_key |
purge_asset_containers |
Comma-separated public container handles (CDN_PURGE_ASSET_CONTAINERS); private assets are skipped |
None |
purge_all_on_static_cache_cleared |
Purge the whole site when Statamic's static cache is cleared (e.g. on deploy) | true |
Set CDN_PURGE_ALL_ON_STATIC_CACHE_CLEARED=false when your deploy already flushes the CDN pull zone, so the static-cache-clear event doesn't trigger a redundant site-wide purge. Per-URL purges on content and asset changes are unaffected.
Using a custom CDN
The native Bunny Core API receives one HTTPS POST /purge?url=… per URL with the AccessKey header. Other endpoint hosts are treated as custom gateways: they must accept POST with a JSON body such as {"urls":["https://example.com/page"]}. Gateways may use access_key or bearer. Redirects are not followed.
CDN_PURGE_API_URL=https://cdn.example.com/api/cache/purge CDN_PURGE_API_KEY=your-api-key CDN_PURGE_AUTH_TYPE=bearer
Usage
With the default invalidator, resolved rules are sent to the CDN before their wildcard coverage is lost in Statamic's local index. A custom invalidator remains in control; its UrlInvalidated events are batched, but rules it never reports cannot be inferred.
How purges are sent
- The URLs Statamic invalidates for one change are purged together by one queued job, instead of one job per URL.
- Direct
UrlInvalidatedevents are deduplicated and flushed at the end of the current request, Artisan command or queue job. - Statamic 6 background recache purges the resolved rules even when no local page is cached. After a successful authenticated warm request, the refreshed URL is purged again so the CDN cannot retain a copy it fetched from the old origin cache.
- With
static_caching.invalidation.rulesset to'all', Statamic flushes its whole static cache without firing an invalidation event. The package then purges every site, the same way it does when the static cache is cleared. - Each logical batch holds up to 50 exact or 15 prefix URLs. The native API receives individual requests; a custom gateway receives one JSON request per batch. Same-type batches are spaced 10 seconds apart for exact URLs, 30 seconds for prefixes. Switching buckets needs no delay.
- A purge-all sends each site's base URL, then
<base URL>/*. A wildcard covered by another site's wildcard (for example/fr/*under/*) is left out.
Asset and query variants
Renaming/moving a public asset purges its previous public URL. Reupload and deletion purge the original file URL. The package does not enumerate Glide derivatives, separately signed URLs or arbitrary query-string cache keys. If your zone varies on those keys, configure versioned image URLs or dispatch PurgeUrlsJob::dispatch([...]) with the actual derivative URLs or a narrowly scoped CDN prefix from your own asset listener. See Bunny's purge types before using a prefix.
Failures and retries
Run a queue worker with a persistent driver such as Redis or database. With a worker:
- A rate-limited purge (HTTP 429) is released back onto the queue. It waits for the time the CDN asks for, but at least as long as the rate limit needs to refill (10 seconds for exact URLs, 30 seconds for wildcards) and at most 5 minutes.
- Server errors and connection failures trigger retries with backoff. If a native batch has already made progress, only unfinished URLs are queued again. Slow batches yield between requests to leave room within Laravel's default worker timeout.
- Jobs keep retrying for up to an hour, independent of the worker's
--tries, and then land infailed_jobs. - A purge the CDN rejects (another 4xx, such as a bad API key) is not retried. The job fails right away so it shows up in
failed_jobs.
The sync driver (and Laravel's in-process deferred queue) cannot release or retry a request. Remaining independent URLs are still attempted. The process waits for the next same-type batch and honors a 429 cooldown before sending more URLs of that type. Use a persistent worker to keep these waits out of editor requests.
CdnPurgeService::purgeUrl(), purgeUrls() and purgeAll() use the same inline transport and pacing, returning false if any request failed.
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.
Maintainer releases
See RELEASING.md for versioning, changelog entries and the release command.