Download the PHP package vormkracht10/laravel-static without Composer

Laravel Static

Supercharge your Laravel application with static file caching. Laravel Static converts your dynamic Laravel responses into static HTML files, dramatically improving performance and reducing server load.

Why Laravel Static?

Traditional Laravel applications generate HTML on every request, hitting your database and executing PHP code repeatedly. Laravel Static solves this by:

• Converting dynamic responses to static HTML files — Serve pre-generated HTML instead of executing PHP on every request
• Reducing server load — Let your web server (Nginx, Apache) serve static files directly
• Improving response times — Static files are served in milliseconds, not hundreds of milliseconds
• Supporting multiple caching strategies — Choose between route-based caching or automatic web crawling
• Handling complex scenarios — Multi-domain support, query string handling, and HTML minification

Requirements

• PHP 8.1 or higher
• Laravel 11.0 or higher

Installation

Install the package via Composer:

Publish the configuration file:

Optionally, publish the migrations if you need database-backed features:

Quick Start

1. Enable Static Caching

Add the STATIC_ENABLED=true environment variable to your .env file:

2. Add Middleware to Routes

Apply the StaticResponse middleware to routes you want to cache:

3. Build the Static Cache

Generate your static files:

That's it! Your routes are now served as static HTML files.

Configuration

The configuration file is located at config/static.php. Here's a breakdown of all available options:

Caching Driver

Enable/Disable

Toggle static caching on or off. Useful for disabling in development while keeping it enabled in production.

Build Settings

Host Whitelist

Restrict which hostnames static caches may be created for. When null (the default), caches are created for every host that hits the middleware. Provide an array of hostnames to only cache those hosts — useful when your app is reachable through multiple domains (e.g. a staging or preview domain) but you only want to cache the canonical ones.

Hostnames are matched against the request host (case-insensitive) and support * wildcards — e.g. *.example.com matches any subdomain (but not the apex example.com, which must be listed separately). To restrict caching to your app's own hostname and its www variant:

File Storage

Additional Options

Precompression (gzip / brotli)

Write precompressed copies of each static file alongside the original so your web server can serve them directly, without compressing on every request. gzip is built into PHP; brotli requires the ext-brotli extension and is silently skipped when it isn't installed.

By default each cached page has page.html, page.html.gz, and (optionally) page.html.br siblings. Compression happens once at cache-write time, so a high level is usually worth it.

Storing only the compressed file. Set keep_uncompressed to false to skip the plain .html copy and roughly halve disk usage. The uncompressed file is only dropped when a compressed one was actually written, so a page is never left with nothing to serve (e.g. brotli requested but ext-brotli missing). The trade-off is that your web server must then serve the compressed file to every client, including the rare one that doesn't send Accept-Encoding: gzip — with nginx that means gzip_static always; plus gunzip on; to decompress on the fly for those clients. If you keep the uncompressed copy, nginx falls back to it automatically.

See Web Server Configuration for serving these files.

Commands

Build Static Cache

Generate static files for all configured routes:

When using the routes driver, only routes with the StaticResponse middleware are cached. When using the crawler driver, the crawler starts from your homepage and discovers all internal links.

Rebuild a single page instead of crawling the whole site — the targeted counterpart to static:clear --uri:

The page is re-rendered through its own route (no clear, no crawl), so only that one cached file is refreshed.

Clear Static Cache

Clear all cached static files:

The command asks for confirmation before clearing. Skip the prompt (e.g. in CI/deploy scripts) with --force:

Clear specific URIs:

Clear by route names:

Clear by domain (useful for multi-tenant applications):

Clear only the cached files generated for requests with a query string (e.g. /products?page=2), keeping the plain query-less pages intact:

Advanced Usage

Multi-Domain Support

Laravel Static supports multi-domain setups out of the box. When include_domain is enabled (default), each domain gets its own cache directory:

Query String Handling

When include_query_string is enabled, different query strings create separate cache files:

HTML Minification

Enable HTML minification to reduce file sizes:

This removes unnecessary whitespace, comments, and optimizes the HTML output using the voku/html-min library.

Bypass Header

During development or testing, you may want to bypass the static cache. The package includes a bypass header mechanism:

This header tells the middleware to skip the static cache and generate a fresh response.

Programmatic Cache Clearing

Use the StaticCache facade to clear cache programmatically:

Programmatic Page Building

Refresh one or more pages without rebuilding the whole site. Each URL is re-rendered through its own route, so only those cached files are written — the targeted counterpart to clear():

To do this off the request cycle, dispatch the queued BuildStaticPage job:

The job is a no-op when static caching is disabled, and a failed render is reported rather than thrown — the page keeps its previous cached copy until the next build.

Custom Crawl Observer

Create a custom crawl observer to customize the crawling behavior:

Update your configuration:

Custom Crawl Profile

Control which URLs get crawled by creating a custom crawl profile:

Excluding Routes from Caching

Routes with parameters cannot be automatically cached (they require specific values). You can also explicitly exclude routes by not applying the middleware:

Preventing index.php in Cached URLs

If your web server isn't rewriting pretty URLs (missing try_files / mod_rewrite), Laravel derives the request root from index.php and can leak it into generated links and cache paths — e.g. /index.php/about instead of /about.

The package guards against this in two ways:

• Path normalization (always on): a leading index.php segment is stripped from the cached file path, so a page requested as /index.php/about is still cached as about.html. This applies to both drivers.

• Force root URL (opt-in): enable force_root_url so that during a build the root URL used by url(), route(), and asset() is forced to config('app.url'), keeping index.php out of the links your pages contain:

  This affects the routes driver (which renders pages in the build process). The crawler driver renders each page in a separate HTTP request, so for it the path normalization above is what keeps cache paths clean — the real fix there is correcting your server's URL rewriting.

Async Cache Generation

Enable on_termination to generate cache files after the response is sent to the user:

This improves perceived performance as users don't wait for the cache file to be written.

Web Server Configuration

For optimal performance, configure your web server to serve static files directly without hitting PHP.

Nginx

Serving precompressed files

If you enabled precompression, turn on nginx's static-precompression modules so it serves the .gz / .br siblings when the client supports them. nginx looks for <file>.gz / <file>.br matching the file it's about to serve, so no path changes are needed — just add:

Place these inside the server (or location) block above. When a .br/.gz sibling exists and the request carries a matching Accept-Encoding, nginx serves it and sets Content-Encoding automatically; otherwise it falls back to the uncompressed file.

Apache

Cache Invalidation Strategies

Event-Based Invalidation

Clear cache when content changes using model events:

Prefer re-rendering the changed page over clearing it when you want the cache to stay warm. Dispatch the BuildStaticPage job so the edited page is rebuilt immediately instead of being regenerated lazily on the next visit:

Scheduled Rebuilds

Add a scheduled task to rebuild your cache periodically:

Deploy Hook

Clear and rebuild cache during deployments:

Comparison: Routes vs Crawler Driver

How It Works

1. Request Interception: The StaticResponse middleware intercepts outgoing responses
2. Eligibility Check: Only GET/HEAD requests with 200 OK status are cached
3. File Generation: HTML content is saved to the configured storage disk
4. Optional Minification: If enabled, HTML is minified before saving
5. Directory Structure: Files are organized by domain, HTTP method, and URI path

The PreventStaticResponseMiddleware (automatically registered) handles bypass headers and ensures proper behavior during cache building.

Troubleshooting

Cache Not Being Generated

1. Ensure STATIC_ENABLED=true is set in your .env
2. Verify the StaticResponse middleware is applied to your routes
3. Check that the storage disk is writable
4. Routes with parameters cannot be cached automatically
5. Only 200 OK responses are cached

Cache Not Being Served

1. Verify static files exist in your storage directory
2. Check web server configuration
3. Ensure the bypass header is not being sent accidentally

Crawler Not Finding Pages

1. Check if pages are linked from the homepage
2. Verify accept_no_follow setting if using rel="nofollow" links
3. Review your crawl profile configuration
4. Note: JavaScript-rendered content is not supported

File Path Too Long

If you encounter file path length errors:

1. Check the filepath_max_length and filename_max_length settings
2. Consider using shorter URLs or disabling query string caching
3. The package will skip files that exceed the configured limits

Testing

Run the test suite:

Run tests with coverage:

Run static analysis:

Format code:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mark van Eijk
• All Contributors

Built with Spatie Crawler and voku/HtmlMin.

License

The MIT License (MIT). Please see License File for more information.