[5.x] Add --header option to static warm command

[ChristianPraiss]

Add support for custom headers in static:warm command

This PR introduces a new --headers option to the static:warm command, allowing users to specify custom HTTP headers for requests made during cache warming, e.g. for:

• Pages requiring authentication or API tokens for access.
• Need to trigger static cache refreshes even when static files are being served, using custom server rules. Especially useful for zero-cache-downtime scenarios

Related docs here: statamic/docs#1674

[jasonvarga]

Thank you for the PR.

The test was nice, thanks! But there was a false positive.

Since you can't pass an array from the CLI (but you can in the test), you need to use the option multiple times as you noted. But, you need to define it in the signature with an asterisk. Running the command from the CLI the way you had it only used the first one you passed in.

Also, since you need to use the option multiple times, and each time it's a singular header, I've changed the option from headers to header.

please static:warm --header="Foo: Bar" --header="Bar: Baz"

[ChristianPraiss]

Always happy to help!

Good to know that, thx for noticing and fixing it right away! The intricacies of artisan commands...

[dominikfoeger]

Hey @ChristianPraiss sorry for misusing the thread but could you elaborate on your zero cache downtime solution? You can reach me in the Statamic Discord or on Bluesky.

[ChristianPraiss]

Hey @dominikfoeger, I don't have any of those networks, but I guess I can share this excerpt from our internal documentation here, that should clarify it a bit:

Setup

We’re using the file caching mode that is recommended by statamic for high traffic sites. Docs: https://statamic.dev/static-caching#file-driver

Basically that means all pages that are not dynamic will be fully rendered and stored on disk, where they will be served by nginx. All pages that nginx does not have statically will be forwarded to statamic to get a freshly rendered response.

Because we are using Docker, a new image will also start out with an empty cache folder. Even if we stored that folder in a volume, it would still be cleared first before warming a new cache, leading to slower response times during cache warming. That’s why we are using separate folders for warming the cache and serving the cache.

We keep the cache live between deploys by storing it in a docker volume that is being reused by newly deployed containers. This way we achieve a full zero-cache-downtime deployment by using that volume as the folder that nginx serves from.

Deployment Workflow

During deployment we run the php artisan statamic:static:warm command with special headers that allow the cache warming command to bypass the nginx cache. Nginx has a rule configured to forward all requests with a specific header to statamic even if it would normally serve the statically cached file for a page.

Once the cache warming is done, the staging-cache directory is copied to overwrite the live cache and will instantly be picked up by nginx.

Folder Structure:

• public/static-staging: This is where statamic is configured to write it’s cache, not stored and will be empty for a new docker container.
• public/static: This is where nginx is serving static file from, stored in a docker volume

[dominikfoeger]

@ChristianPraiss that's smart, thank you very much for sharing!