Static Cache Buster Laravel Package

Getting Started

This package targets a specific Statamic pain point: after content changes or a deploy, static caches are invalidated and the next visitor pays the cost of regenerating the page. The package warms those pages ahead of traffic so visitors never hit the uncached path.

Minimal steps:

1. Install it into a Statamic project with static caching already enabled (config/statamic/static_caching.php, strategy set to half or full):

   composer require f_roepstorf/static-cache-buster
   

2. Publish any package config:

   php artisan vendor:publish --tag=static-cache-buster-config
   

3. Discover the entry point before writing any integration code. Because this is a zero-star package with no ecosystem around it, verify the actual API rather than assuming:

   php artisan list | grep -i -E "cache|warm|buster"
   ls vendor/f_roepstorf/static-cache-buster/src
   

   Read the service provider to see whether it registers commands, listeners, or a queue job — that dictates how you wire it in.
4. Ensure APP_URL matches the host you actually serve, and that the warm requests can reach the front end unauthenticated.

Where to look first: the package's README, its service provider, and config/static-cache-buster.php after publishing. Those three files tell you the command name, config keys, and whether it hooks into Statamic's cache-invalidation events automatically.

First use case: a post-deploy warm. Instead of letting the first users after a deploy absorb cold-start latency, run a warm step at the end of your deploy pipeline against the origin (not the CDN), then let traffic in.

Implementation Patterns

Post-deploy warm in CI/CD

The highest-leverage use is a deploy step. Warm against the origin host directly, so you don't pollute the CDN edge with half-warmed responses:

# after artisan migrate / config:cache, before flipping traffic
php artisan <package-warm-command> --url="${ORIGIN_URL}"

Keep this step time-boxed. If warming takes longer than your deploy budget, move it to a queued job or a scheduled command instead of blocking releases. A warm that runs for 20 minutes is worse than a cold cache.

Event-driven re-warm after content changes

Statamic fires save events for content. The idiomatic pattern is to queue a re-warm for the affected URL rather than warming the whole site:

use Illuminate\Support\Facades\Queue;
use Statamic\Events\EntrySaved;

Event::listen(function (EntrySaved $event) {
    $uri = $event->entry->uri();

    Queue::push(function () use ($uri) {
        // Warm just this URL via the package's warmer/command
        Artisan::call('<package-warm-command>', ['--url' => url($uri)]);
    });
});

Two rules of thumb:

• Prefer queueing over sync. Content saves happen in the control panel request lifecycle; a synchronous warm makes the editor's save feel slow and can time out on full-site invalidation.
• Deduplicate. A bulk import can fire hundreds of save events. Use ShouldBeUnique on the job or coalesce per-URL warm requests within a short window.

Sitemap-driven bulk warm

For scheduled warming (nightly, or after large imports), drive the URL list from your sitemap rather than hand-maintaining a list:

$urls = collect(explode("\n", file_get_contents(public_path('sitemap.xml'))))
    ->filter(fn ($line) => str_contains($line, '<loc>'))
    ->map(fn ($line) => trim(strip_tags($line)))
    ->filter();

Warm those URLs with bounded concurrency — the package's config usually exposes something like concurrency, timeout, and bypass headers. Start at low concurrency (2–4) against a single origin.

Bypass headers and internal requests

Some Statamic static-cache setups will serve an existing cached file before your request reaches the app, which means your "warm" is a no-op. Check whether the package (or Statamic's middleware) supports a bypass header and send it if you need to force regeneration:

curl -s -o /dev/null -w "%{http_code} %{time_total}\n" \
  -H "X-Statamic-Static-Cache: bypass" \
  https://origin.example.com/about

Confirm the exact header name in the package/Statamic source for your version — it has changed across Statamic versions.

Verifying the warm actually worked

Don't trust exit codes. Assert on the result:

# First request after invalidation should be fast AND have the cache header set
curl -sI https://origin.example.com/about | grep -i static-cache

Also watch the cache directory (storage/statamic/static for full strategy, or your configured path) before and after to confirm files appear.

Local development

Warming is usually pointless in local dev and can mask cache-miss bugs. Gate it behind an environment check or only run it in production/staging so you still see real cold-cache behavior while developing.

Gotchas and Tips

• Pin the version and read the source. A package with zero stars and zero dependents has not been battle-tested by anyone but its author. Pin to a tag/commit, skim src/ for anything dangerous (arbitrary HTTP calls, unserialize, shelling out), and be prepared to fork. Treat it closer to a snippet than a dependency.
• Warming through the CDN is usually wrong. If Cloudflare/Fastly sits in front, warming via the public hostname can cache partial responses at the edge and won't reliably hit your origin. Warm the origin hostname directly and let the CDN populate naturally.
• Authenticated sessions poison the warm. Statamic static caching is user-agnostic — if your warm request carries a session cookie or Authorization header, you can cache a personalized or logged-in page. Use a clean, unauthenticated HTTP client.
• Half vs full strategy behave differently. With half, cached pages still hit the app middleware; with full, Statamic writes and serves flat files. Confirm what "warm" means in each mode — for full, the file must exist on disk; for half, the response cache entry must be populated.
• 404s and redirects are easy to miss. A warm job that silently follows redirects to /login or swallows 404s will report success while caching nothing useful. Capture the status code per URL and fail loudly on unexpected codes.
• Query strings and canonical URLs. Warm only canonical, query-string-free URLs. Statamic's static caching generally treats query strings as bypasses, so warming ?utm_source=... variants wastes requests.
• Multi-site and locales. For multisite installs, URLs are per-site; ensure the warmer iterates every site or you'll have cold locales. Check whether the package resolves sites from the request host or from config.
• Concurrency vs origin health. A naive "warm everything at 50 parallel requests" will melt a small VPS and may trip rate limiting or WAF rules. Ramp up and align with your queue worker count.
• Invalidation races. If content is saved while a warm is in flight, you can re-cache the page the invalidation just removed. Either serialise per-URL with a lock or let the save event win by dropping in-flight warm results for that URL.
• Queue sizing matters. Event-driven warm is only as good as your queue. If your workers are backed up, the "warm" arrives minutes late and visitors still hit misses. Monitor queue depth; consider a dedicated queue for warmth.
• Extension points to look for: config for URL sources, headers, concurrency, and timeout; an artisan command you can call from CI; and any event listener you can disable if it double-fires alongside your own. If the package hardcodes any of these, that's a fork candidate.
• Budget a regression test. Add a simple test that (a) triggers a content save and (b) asserts the warmer was dispatched. Because the package is unmaintained-by-popularity, that test is your early warning if a Statamic upgrade breaks the integration.