[6.x] Hybrid Glide image caching

[duncanmcclean]

This pull request implements a new "hybrid" caching strategy for Glide image manipulation.

The Problem

Statamic currently offers two Glide caching modes:

• Dynamic (cache: false) — Fast template rendering, but every image request hits PHP, even after the image has already been generated.
• Static (cache: true) — Images are served directly by the web server, but they're all eagerly generated during template rendering. A page with 10 images × 11 variants = 110 images blocking the page from even loading.

Hybrid Caching

Setting cache to 'hybrid' enables a new mode that combines the best of both:

// config/statamic/assets.php
'image_manipulation' => [
    'route' => 'img',
    'cache' => 'hybrid',
    'cache_path' => public_path('img'),
],

The Glide tag outputs a URL pointing to where the cached image will live, but doesn't generate the image during template rendering. When the browser requests the image:

1. If the file already exists on disk, the web server (Nginx/Apache) serves it directly — no PHP needed.
2. If the file doesn't exist yet, the request falls through to PHP, which generates the image, saves it to the public cache_path, and serves it.

After the first request, the web server serves the static file directly on all subsequent requests. The default Nginx/Apache/IIS configurations handle this automatically — no additional rewrite rules are needed.

The cache_path must be the route directory inside public/ (e.g. public/img for the img route), otherwise the generated files are never reachable by the web server. A warning is logged once if they don't line up.

How It Works

• A new GlideCachePathResolver predicts the deterministic cache path for an image without generating it. This is the same path the generator writes to, so hybrid URLs are identical to the ones cache: true produces for the same image.
• A new HybridUrlBuilder builds URLs from that cache path, and stores a mapping (hybrid::<cache path> → source + params) in the Glide cache store so the controller knows how to generate the image later. Mappings for assets are added to the asset's existing manifest.
• Hybrid mode registers a single {route}/{path} route. The GlideController handles the PHP fallback: if the file already exists it serves it (logging a one-time warning, since the web server should have served it), otherwise it looks up the mapping and generates the image on demand. Unknown paths 404.
• Cache invalidation works through the existing logic: clearing an asset deletes its files and forgets its mappings via the manifest, and php please glide:clear deletes the files and flushes the mappings.
• RemoteUrlValidator::parse() no longer resolves DNS, so remote URL cache paths can be computed during rendering without a lookup. The public IP check now lives in resolve()/validate(), and everything that actually fetches a remote image still calls it first.

Notes

• {{ glide:generate }} still generates eagerly, since it needs the image's dimensions.
• Switching from cache: false to 'hybrid' changes image URLs (as switching to true does), so old /img/asset/… and /img/http/… URLs will 404. Switching from true keeps the same URLs.
• The hybrid cache is always on the local public disk; custom filesystem disks aren't supported in this mode.
• Since mappings live in the Glide cache store, load-balanced setups need a shared cache store, and statically cached pages should be re-rendered after glide:clear.

---

Closes statamic/ideas#1420

Docs PR: statamic/docs#1899

[daun]

🔥

[jasonvarga]

Hybrid approach looks great overall — one bug to address before merging (inline). A few smaller notes I'll leave as a follow-up comment so they don't block.

[jasonvarga]

Did a bit of a more thorough review and this introduces a security issue in its current state. I've marked it as draft so we don't merge prematurely.

Changes were made but there's more to do.

[aaronbushnell]

Ooo really looking forward to this one! 🔥

[jasonvarga]

The hybrid design itself is solid — the clean URL is only generatable from a mapping the server wrote during rendering, so the mass-resize vector is closed for hybrid's own URLs. I checked this out and exercised it; the inline comments are the things that need fixing before this can merge. One is a page-breaking crash, the rest are correctness/security gaps in the surrounding routes.

Non-blocking, but worth doing while you're in here:

• generateOnDemand() passes the raw request path to Glide::cacheDisk()->exists(). Paths like /img/../../.env throw League\Flysystem\PathTraversalDetected (correctly blocked, no disclosure) but surface as a 500 rather than a 404. Catch it and 404.
• Direct serving only works when route matches the public-relative cache_path (img / public_path('img')), and nothing checks that. If someone changes one, every image request silently hits PHP forever. Worth a docs note or a boot-time warning.
• A published hybrid URL is only resolvable while its mapping survives in the Glide cache store. On a statically cached site, losing storage/framework/cache/glide (e.g. a container redeploy) while the HTML is retained means those images 404 permanently. Docs note at minimum.
• resolveForUrl() and the 'url' mapping branch have no tests.

[jasonvarga]

These nine commits address everything from the last review — I re-checked each one against the code and tests and all five are properly fixed, not papered over:

• b0b8138 resolves id items once and throws AssetNotFoundException, which Tags\Glide catches, so the missing-asset page crash is gone.
• 56f1f5b drops the /asset and /http routes in hybrid mode entirely, which closes the mass-resize vector independently of secure.
• a1de853 shares the mark encoding and hashes ImageGenerator::watermarkParam() on both sides. I traced all three watermark shapes (Asset, remote URL, plain path) and they agree now.
• 8fe77e4 splits the validator correctly. I checked every RemoteUrlValidator call site — ImageGenerator::parseUrl() and GuzzleAdapter both still resolve before fetching, so there's no SSRF regression against #14761.
• aa44e90 drops secure => false, so the tests now cover the shipped default.

The non-blocking notes are handled too (773e2eb, 0088bae, ff8fb4b).

I did find three more things, and they're all the same bug wearing different hats: the predicted path and the path the generator actually writes to diverge. Each one fails silently — the response is correct, so nothing looks broken, but the file never lands where the browser asked for it, the web server can never serve it, and every request boots PHP forever. That's exactly the watermark bug again.

Which is the real point here: a1de853 fixed watermarks specifically rather than fixing the class. I think this wants a test helper that asserts resolveFor*() equals what ImageGenerator writes, driven over a table of inputs — asset, path, remote URL, watermark, video, prefixed site. That would have caught all three of these and would stop the next one. Right now nothing in the suite checks the invariant the whole design rests on.

Non-blocking:

• Changing image_manipulation.defaults or a preset between render and request re-points the hash, so the requested file never appears and the image is re-manipulated on every subsequent request. It self-heals on the next render, so it mostly doesn't matter — except on a statically cached site, where the stale HTML keeps the old URL indefinitely. Worth a docs line about clearing static caches after changing image defaults.
• The boot warning added in 0088bae fires on every request and every artisan command while misconfigured, not once. Same log-noise shape as the existing "rewrite rules" debug line.
• ImageGenerator::watermarkParam() is typed : string, but decodeWatermark() returns Assets::find(...), which is null if the watermark asset was deleted between render and generation. That's a TypeError now where it used to degrade to an unmarked image. Edge case, image route only, and the old behaviour was also wrong.
• Unrelated to the above: video assets 500 on the glide route when ffmpeg isn't available, because generateByAsset() returns '' and createResponse('') resolves to the cache root. I measured the same 500 on cache: false, so it's pre-existing and not yours to fix — just noting it while we're in here.

[duncanmcclean]

Thanks Jason! Agreed on the root cause, so I've added the test you suggested alongside the fixes.

Blocking

• 08f2956 — hybrid_caching_generates_the_image_where_the_url_points builds a URL, requests it, then asserts the file exists at public_path(rawurldecode($url)), which is the file the web server would serve. It runs over a table of inputs: asset, auto crop, asset id, path, remote URL, all three watermark types, plus the cases below. It replaces the old predicted-vs-generated tests.
• 7038912 — each segment of the cache path is now rawurlencoded, so #, spaces, ? and a literal % all survive. Covered by an asset named photo #1.jpg, a remote URL with a query string and a remote URL containing %23.
• ffb172b — I went with root-relative URLs, since the cache path is already shared between sites. That matches what cache: true does today. The hybrid route is now registered once without a site prefix, so it's still reachable when every site has one. That also means cachePathIsServedByRoute() is correct as it stands. There's a table row for a /fr/ site and a route test for the "every site is prefixed" case.
• a38ff33 — resolveForAsset() now has a video branch that predicts paths/thumb_<md5>.jpg/…. The filename comes from a new ThumbnailExtractor::getFileName(). There's a table row for a video with ffmpeg faked.

Non-blocking

• 48b3cbc — watermarkParam() is nullable again, so a deleted watermark asset produces an unmarked image instead of a TypeError.
• cf0ac87 — the misconfiguration warning is logged once, using a flag in the Glide cache store. It'll warn again after glide:clear.
• Static cache after changing image defaults: I'll add a line to the docs PR (Hybrid Glide image caching docs#1899). While I'm there I'll also note that:
  • the Glide cache store has to be shared between servers behind a load balancer
  • glide:clear removes the mappings, so stale cached HTML will 404
  • switching an existing site to hybrid 404s old /img/asset and /img/http URLs
• Video 500 without ffmpeg: I've left it alone since it isn't new, as you said.

Changes made