Index of every page on this site: llms.txt
All skills
vondry avatar

/bolt-asset-caching

@083eb14
Run it yourself

Use this skill whenever setting up, optimizing, or debugging client/CDN HTTP caching for Bolt CMS images, thumbnails, CSS, JS, and PDFs. Resolves the critical Symfony SessionListener bug where stateful firewalls rewrite League Glide's public 1-year thumbnail cache to private/no-cache, configures Bolt's save_files thumbnail disk dump, sets up Apache mod_expires and Nginx static expires rules, establishes frontend asset cache-busting (?v=X.X), and checks end to end — Apache with the project's .htaccess plus PHP-FPM, or production — that every thumbnail and upload is served from disk with ETag, Last-Modified, max-age and 304s instead of by PHP.

  • 8 files
  • 57 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/vondry/bolt-skills/bolt-asset-caching

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈168 tokens for metadata: the name and description. ≈4.7k when used: this file. ≈303 more on demand in 2 files.

Description uses 8.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈670 characters, or 8.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Bolt CMS Full-Stack Asset & Thumbnail Caching

In Bolt CMS websites, media files, thumbnails, and compiled stylesheets/scripts account for the vast majority of HTTP requests and bandwidth. Without end-to-end caching configuration across Symfony, Bolt core, and the web server (Apache/Nginx), browsers will re-download assets on every visit, degrading Core Web Vitals and overloading PHP-FPM.

This skill documents the complete multi-layer asset caching architecture established across production Bolt CMS repositories.


1. The Core Root Cause: The Symfony Thumbnail Cache Destruction Bug

Why Thumbnails Were Not Being Cached:

  1. Glide's Intended Behavior: Bolt CMS dynamically generates manipulated thumbnails on demand via Bolt\Controller\ImageController using League Glide. Under the hood, Glide sets a public one-year cache header:
    Cache-Control: max-age=31536000, public
    Expires: ...
    It sends no ETag and no Last-Modified, so a browser can't revalidate a thumbnail that PHP served (no 304 Not Modified); once the year is over, or after a hard reload, it downloads the whole image again. Only a thumbnail saved to disk and served by Apache / Nginx (Step 2) gets ETag, Last-Modified and 304s.
  2. The Default Symfony Firewall: In standard Symfony and Bolt starter configurations (config/packages/security.yaml), the stateless dev firewall (which disables security tokens and session handling) only matched:
    firewalls:
      dev:
        pattern: ^/(_(profiler|wdt)|css|images|js)/
        security: false
    Notice that /thumbs is omitted.
  3. The Silent Downgrade: Requests for /thumbs/320x240/hero.webp fall through to Symfony's stateful main firewall (pattern: ^/). The main firewall initializes the security token and touches the user session. When Symfony's SessionListener executes on the response, it detects an active session context and overwrites Glide's public cache header with:
    Cache-Control: private, must-revalidate, max-age=0
  4. The Impact: Browsers and CDNs (Cloudflare, Fastly, etc.) strictly obey private, max-age=0 and refuse to store thumbnails in disk or memory cache. Every page reload triggers full image transfers and forces PHP to repeatedly handle thumbnail requests!

2. Multi-Layer Caching Architecture

To achieve optimal performance, assets are cached through four synchronized layers:

Request Path:
Browser / CDN
  │
  ├── 1. Direct Web Server Static Cache (Apache mod_expires / Nginx expires 2M)
  │      └── Serves public/files/, public/assets/, and disk-saved public/thumbs/
  │          straight from disk without booting PHP.
  │
  └── 2. First-time Thumbnail Generation (/thumbs/...)
         └── Handled by Symfony / Bolt ImageController
             │
             ├── Bypass Firewall (security.yaml): No session touched -> Glide sends public, max-age=31536000.
             └── Disk Dump (config/bolt/config.yaml save_files: true):
                 Saves to public/thumbs/ so subsequent requests hit Layer 1 directly!

3. Step-by-Step Implementation

Step 1: Bypass the Security Firewall for /thumbs

File: config/packages/security.yaml

Update the dev firewall pattern to explicitly include thumbs:

# config/packages/security.yaml

security:
  firewalls:
    dev:
      pattern: ^/(_(profiler|wdt)|css|images|js|thumbs)/
      security: false
  • Why this works: The /thumbs/ route is now processed statelessly. No security listeners or session managers run, preserving League Glide's Cache-Control: public, max-age=31536000 header on the HTTP response.

Step 2: Enable Thumbnail Disk Caching (save_files: true)

File: config/bolt/config.yaml

Ensure save_files: true is configured in the thumbnails section:

# config/bolt/config.yaml

thumbnails:
  default_thumbnail: [ 320, 240 ]
  default_image: [ 1000, 750 ]
  quality: 80
  cropping: crop
  # Save generated thumbnails directly to public/thumbs/ on disk
  save_files: true
  allow_upscale: false

# The upload whitelist (accept_file_types / accept_media_types) is part of
# bolt-security-hardening (examples/config_snippet.yaml).
  • How this operates:

    1. First request: The file does not exist on disk in public/thumbs/. The request hits PHP, generates the thumbnail, streams it back to the user, and dumps the binary to public/thumbs/{parameters}/{filename}.
    2. Subsequent requests: Apache and Nginx find the file directly on disk via standard static file rules and serve it directly with 0 ms PHP overhead!
  • bolt/core 6.0.1 – 6.1.x: these versions save thumbnails to public/thumbs/<w>_<h>_<q>_<fit>_<location>/ (e.g. 400_300_80_crop_files/), a path no thumbnail URL points to. The web server never finds them, so every /thumbs/… request still runs PHP (with Glide's headers from section 1). No fix is coming in 6.x: bolt/core PRs #3828 and #3829 were closed unmerged, and the maintainers plan a new thumbnail route for Bolt 7 (bolt/core #3840). Thumbnails keep working, just through PHP; once a release fixes it, delete the unused public/thumbs/*_files/ folders (locally and on the server). scripts/verify.sh detects the affected versions in vendor/, and the delivery check (section 4) shows where each thumbnail actually comes from.


Step 3: Configure Apache Static Expiration (public/.htaccess)

File: public/.htaccess

Add the mod_expires configuration block. bolt-htaccess owns public/.htaccess and ships the same block: keep one <IfModule mod_expires.c> and merge missing types into it — a second block makes it unclear which rules apply.

# public/.htaccess

<IfModule mod_expires.c>
    ExpiresActive On

    # Images (uploads in public/files/ and disk thumbnails in public/thumbs/)
    ExpiresByType image/avif "access plus 2 months"
    ExpiresByType image/gif "access plus 2 months"
    ExpiresByType image/jpeg "access plus 2 months"
    ExpiresByType image/png "access plus 2 months"
    ExpiresByType image/svg+xml "access plus 2 months"
    ExpiresByType image/webp "access plus 2 months"
    # Favicons keep a fixed URL (no ?v=), so a shorter lifetime. Apache names .ico
    # image/vnd.microsoft.icon (current mime.types) or image/x-icon (older).
    ExpiresByType image/vnd.microsoft.icon "access plus 1 week"
    ExpiresByType image/x-icon "access plus 1 week"

    # Documents
    ExpiresByType application/pdf "access plus 2 months"

    # Frontend assets (styles, scripts) — cache-busted with ?v={{ theme.assets_version }}.
    # Apache serves .js as text/javascript (newer mime.types) or application/javascript (older).
    ExpiresByType text/css "access plus 2 months"
    ExpiresByType text/javascript "access plus 2 months"
    ExpiresByType application/javascript "access plus 2 months"

    # Fonts
    ExpiresByType font/woff2 "access plus 1 year"
    ExpiresByType font/woff "access plus 1 year"
</IfModule>
  • Without this block Apache sends uploads and saved thumbnails with ETag and Last-Modified but without max-age / Expires, so browsers revalidate every image on every page view. scripts/verify.sh fails when the block is missing.
  • TTL Rationale: A 2-month window (access plus 2 months) provides maximum cache hit rates while dropping must-revalidate, allowing browsers to serve assets instantly from disk cache.
  • JavaScript MIME types: current Apache mime.types serve .js as text/javascript; older ones as application/javascript. List both, otherwise scripts get no expiry header on newer servers.

Step 4: Configure Nginx Static Expiration (docker/nginx/conf.d/default.conf)

File: docker/nginx/conf.d/default.conf

The /theme/, /files/ and /thumbs/ locations come from bolt-security-hardening (examples/docker/nginx_security.conf): they serve only allowlisted file types, set expires 2M, and pass a thumbnail that is not on disk yet to Bolt (try_files $uri /index.php). Use that file; do not add a second /thumbs location — Nginx refuses duplicate locations.

For the rest of public/ (Bolt's admin assets in /assets/ and /bundles/, a favicon in the root) add the generic static block from examples/nginx_static.conf:

location ~* ^.+\.(?:avif|css|gif|ico|jpe?g|js|png|svg|webp|woff2?|ttf|otf|webmanifest|pdf|mp4|webm)$ {
    access_log                    off;
    log_not_found                 off;
    expires                       2M;
    try_files                     $uri =404;
}
  • No add_header in these locations. An add_header inside a location drops every add_header of the server block for that location — the HSTS and nosniff headers of bolt-security-hardening would disappear from every image. expires 2M already sends Cache-Control: max-age=5184000; an extra add_header Cache-Control "public" would send a second Cache-Control header, and Pragma has no effect on modern browsers.

Step 5: Frontend Asset Cache-Busting (?v=X.X)

Because CSS and JS are now served with 2-month caching, browsers will not check the server for updates until the cache expires. To ensure instant updates upon releasing new styling or scripts, append a version query string to asset paths in the theme's layout shell. The version lives in theme.yaml (assets_version), so a release changes one line:

{# public/theme/<theme_name>/partials/_master.twig (bolt-theme-init) #}

<link rel="stylesheet" href="{{ asset('css/index.css') }}?v={{ theme.assets_version|default('1.0') }}">
<script defer src="{{ asset('js/app.js') }}?v={{ theme.assets_version|default('1.0') }}"></script>
# public/theme/<theme_name>/theme.yaml
assets_version: '1.4'

Whenever CSS or JS is rebuilt for a new release, bump assets_version (e.g. '1.3' → '1.4'), forcing all browsers to immediately fetch the new files while retaining long-lived caching. A hard-coded ?v=1.3 in the template works the same way but has to be changed in every layout that loads the assets (partials/_master.twig, helper-pages/_helper_template_without_master.twig). Bolt registers the active theme as the default asset package on frontend and error pages, so asset('css/index.css') resolves to /theme/<theme_name>/css/index.css.


4. Verification & Testing

1. Automated Verification Script

Run the automated test runner:

skills/bolt-asset-caching/scripts/verify.sh

The script verifies:

  1. config/packages/security.yaml dev firewall contains thumbs (^/(_(profiler|wdt)|css|images|js|thumbs)/).
  2. config/bolt/config.yaml has thumbnails.save_files: true.
  3. public/.htaccess has mod_expires.c with image expiration rules (fails without them); warns when JavaScript is listed only as application/javascript (without text/javascript) or when more than one mod_expires block exists.
  4. docker/nginx/conf.d/default.conf (if present) has expires and try_files for /thumbs.
  5. vendor/bolt/core saves thumbnails at the path of their URL; warns on bolt/core 6.0.1 – 6.1.x (Step 2).
  6. If a Symfony CLI server runs for the project: the Cache-Control of a generated thumbnail is public, not private, max-age=0.
  7. The end-to-end delivery check below, when scripts/serve-apache.sh is running for the project or BOLT_DELIVERY_URL points at a staging / production site (fails on any thumbnail or upload not served from disk with full cache headers). It does not use BOLT_BASE_URL, which is usually symfony serve (bolt-audit sets BOLT_DELIVERY_URL from its --base-url when Apache or Nginx answers there). The quick header check of one thumbnail before it runs against BOLT_BASE_URL when set and reachable, otherwise against the project's symfony serve.

The configuration checks can all pass while every thumbnail still runs PHP (bolt/core 6.0.1 – 6.1.x, a read-only public/thumbs/, a web server rule that never looks on disk). Only the delivery check shows what the web server actually does.

2. End-to-End Delivery Check (scripts/check-delivery.php)

Crawls the running site (/sitemap.xml and links), collects every image the pages reference — /thumbs/…, /files/…, theme images, srcset, CSS url(), icons, og:image — and requests each one three times:

  1. first request — may go to PHP, which generates and saves the thumbnail;
  2. second request — must come from disk, with ETag, Last-Modified and a max-age;
  3. conditional request with the ETag / Last-Modified of the second — must answer 304.

It fails when a thumbnail or upload doesn't; theme images only warn, and image URLs that answer 404 are listed as broken references.

Run it against the web server the site runs on in production. symfony serve and PHP's built-in server ignore .htaccess and send uploads without ETag and Cache-Control; the check warns when the responses look like that. For an Apache site, scripts/serve-apache.sh serves the project locally like the production host — Apache with the project's own root and public/ .htaccess files, PHP-FPM in prod — and sets up a PHP-FPM access log that records which requests reached PHP:

bash $SKILLS/bolt-asset-caching/scripts/serve-apache.sh start --port=8090      # prints the commands below
php $SKILLS/bolt-asset-caching/scripts/check-delivery.php \
    --base-url=http://127.0.0.1:8090 --fpm-log=var/serve-apache/logs/php-fpm-access.log
bash $SKILLS/bolt-asset-caching/scripts/serve-apache.sh stop

serve-apache.sh needs Apache (httpd / apache2 with mod_rewrite, mod_expires, mod_headers, mod_proxy_fcgi) and php-fpm; it writes only to var/serve-apache/ (kept out of git status), and Symfony builds var/cache/prod on the first request. Run bin/console cache:clear --env=prod first if that cache is stale. The check sends X-Forwarded-Proto: https to local URLs, so the root .htaccess HTTPS redirect stays quiet.

While serve-apache.sh runs, scripts/verify.sh (and verify-all.sh) include the delivery check automatically. The same script works against staging or production (--base-url=https://example.com, or BOLT_DELIVERY_URL=https://example.com for verify.sh; read-only GET requests). Without --fpm-log it counts a response without ETag and without Accept-Ranges as PHP — Bolt's thumbnail responses send neither, Apache and Nginx send both for static files. Add --alias=www.example.com when the pages link to the site under another host name, --details to list every URL, --json=report.json for the raw results.

A passing site looks like this (a thumbnail goes through PHP once, when it is generated):

category  URLs  1st PHP  2nd disk  2nd PHP    broken  ETag  LastMod  max-age   304
thumbs      69       69        69        0         0    69       69       69    69
files       53        0        53        0         0    53       53       53    53

On bolt/core 6.0.1 – 6.1.x the same site shows 2nd PHP 69, no ETag / Last-Modified and no 304s for thumbnails. A freshly saved thumbnail can carry a weak ETag (W/"…"): Apache marks files changed within the last second as weak; 304s work the same.

3. Manual HTTP Header Inspection

Test live response headers using curl -I:

# 1. Test thumbnail headers (request it twice — the first request may generate it)
curl -I https://example.com/thumbs/320x240/foto/hero.webp

# Expected Headers (served from disk):
# HTTP/2 200
# cache-control: max-age=5184000
# etag: "..."
# last-modified: ...
# A response without etag / last-modified and with max-age=31536000, public came from PHP (Glide).
# It must never contain "private, max-age=0".

# 2. Test static media headers
curl -I https://example.com/files/foto/hero.webp

# Expected Headers:
# HTTP/2 200
# cache-control: max-age=5184000 (or expires in 2 months)

# 3. Test CSS/JS cache headers
curl -I https://example.com/theme/mytheme/css/index.css?v=1.1

5. Common Pitfalls & Solutions

Pitfall 1: Session Started in Custom Middleware

  • Symptom: Even with thumbs in security: false, headers occasionally show private.
  • Cause: A custom EventSubscriber or Twig extension injected RequestStack::getSession() without checking hasSession().
  • Fix: Never start sessions for asset routes or ensure session calls are guarded by if ($request->hasSession()).

Pitfall 2: Thumbnails Still Served by PHP Despite save_files: true

  • Symptom: the delivery check reports thumbnails as 2nd PHP; their responses have Cache-Control: max-age=31536000, public but no ETag / Last-Modified, and public/thumbs/ fills with folders like 400_300_80_crop_files/.
  • Cause: bolt/core 6.0.1 – 6.1.x save thumbnails to a path no thumbnail URL points to (Step 2).
  • Fix: none in the project — wait for a bolt/core release that fixes it (PRs #3828 / #3829 were closed unmerged; a new thumbnail route is planned for Bolt 7, bolt/core #3840), then delete the unused public/thumbs/*_files/ folders. Until then thumbnails keep working through PHP, with Glide's year-long Cache-Control; list it as an expected warning in the site plan.

Pitfall 3: public/thumbs/ Directory Permissions

  • Symptom: Bolt logs Cannot dump file public/thumbs/... Permission denied.
  • Cause: the PHP process (PHP-FPM user, or the hosting account) cannot write to public/thumbs/.
  • Fix (server with a shell):
    mkdir -p public/thumbs
    chmod -R 775 public/thumbs
    chown -R www-data:www-data public/thumbs
  • Fix (SFTP shared hosting): PHP runs as the hosting account, which owns the uploaded files, so chown is neither possible nor needed. Create public/thumbs/ in the SFTP client and give it write permission for the owner (755; 775 only when the host's panel says PHP runs as a different user). Never upload public/thumbs/ from a local machine — the server generates its own.

Pitfall 4: A Replaced Upload Keeps Its Old Version for Two Months

  • Symptom: an editor replaces files/logo.png with a new file under the same name; visitors keep seeing the old one.
  • Cause: uploads are cached for two months (access plus 2 months) and their URL did not change — unlike CSS and JS, they have no ?v= version.
  • Fix: upload the new version under a new name (logo-2026.png) and pick it in the record. Thumbnails of the old file stay valid for the old URL only.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 083eb14. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 3 weeks ago

README badge

README badge for vondry/bolt-skills/bolt-asset-caching