Download the PHP package codegenie-be/laravel-config-cache-guard without Composer

Laravel Config Cache Guard

by Codegenie

Never serve stale Laravel configuration or routes after an FTP or shared-hosting deployment, even when exec() is disabled.

Laravel Config Cache Guard detects relevant deployment changes before Laravel boots, prevents stale cache files from being used and safely repairs them through the PHP CLI or Laravel's own Artisan::call() fallback.

It is built for Laravel 12 and 13 applications deployed through FTP, cPanel, Plesk or other environments where deployment hooks, SSH or shell functions may be unavailable.

Quick start

That single Composer command completes installation. Optionally verify the integration with:

No public/index.php change is required. The guard is loaded automatically by Composer when Laravel requires vendor/autoload.php, before bootstrap/app.php bootstraps the application.

• Open the package website
• Watch the verified repair flow
• Read the deployment recipes
• Ask a question

Who this is for

Use this package when your application already uses config or route cache and:

• you deploy through FTP, cPanel, Plesk or shared hosting
• deployment cache commands can occasionally be skipped
• SSH, exec() or a reliable deploy hook is unavailable
• you want stale cache to be rejected before Laravel can load it
• you need a small file-based safety net without Redis, queues, cron or a database

Do not use it as a replacement for a correct deployment pipeline. A deployment that can reliably run Laravel's cache commands should keep doing so.

By default, the package does not create config cache when none exists and does not enable route caching for applications that are not already using it.

Verified repair demo

The animation is a concise transcript of the real Laravel 13, process-control-disabled scenario covered by the full package E2E suite. Read the accessible transcript and verification notes.

This package is a safety net. When your host exposes reliable destination-side deployment commands, rebuilding Laravel deployment caches there remains the preferred production flow. FTP-only/shared hosting without command access is explicitly supported through the in-app fallback.

Why this exists

Laravel normally caches configuration into:

Laravel 13 can use .laravel/cache as its active bootstrap cache directory, and Laravel also supports an explicit APP_CONFIG_CACHE path. Routes are normally cached in files such as:

Those caches are good for production performance, but relevant deployment changes are not reflected until the appropriate cache is rebuilt. This includes changes to .env, configuration, routes, application providers, bootstrap registration and installed dependency metadata.

Config cache also is not necessarily portable between filesystem locations. Laravel configuration can contain absolute application or storage paths, so a cache generated in CI, on a developer machine, on staging or in a previous release directory can be unsafe after relocation even when the source files themselves are unchanged.

This is easy to miss on shared hosting, FTP deployments or hosting panels where deploy hooks are limited. The package checks source state before Laravel bootstraps and binds config signatures to the current runtime identity. If source state or the config runtime identity changed, it prevents Laravel from using stale deployment cache and tries to rebuild safely.

When bounded process control is unavailable, the package removes stale config cache, points Laravel at a current signature-based route cache path, and queues an internal in-app auto repair. After the current HTTP response is sent, the package can rebuild through Laravel's own Artisan::call() without SSH, tokens or public repair URLs.

What it does

On normal HTTP requests, the guard checks relevant deployment sources against:

• .env
• .env.{APP_ENV} when APP_ENV is provided as a real server environment variable
• config/**/*.php when config cache guarding is active, and also for route signatures because route registration can depend on configuration
• routes/**/*.php when a route cache file already exists
• app/Providers/**/*.php
• the active bootstrap app.php and providers.php files (bootstrap/* or .laravel/*) when they exist
• composer.json and composer.lock when present, so dependency or package-discovery changes invalidate deployment caches

The default metadata signature mode uses fast metadata such as timestamps, file size and inode metadata. Optional content mode hashes source-file bytes in memory to catch same-size rewrites that preserve metadata. Neither mode stores source contents or .env values.

Config signatures additionally include a one-way runtime identity derived from the normalized application base path, canonical base path and OS family. This means a signed config cache moved to another application path or operating system is rejected even when its source files are otherwise identical. Raw runtime filesystem paths are not persisted in the signature file. Route signatures remain source-based because route cache does not need the same config-path portability protection.

By default, config cache guarding refreshes the existing config cache in Laravel's active bootstrap cache directory. It also supports an explicit APP_CONFIG_CACHE path when that path is available as a real process or server environment variable before Composer loads. It does not force config caching on projects that are not using config cache. You can opt into creating config cache when missing with CONFIG_CACHE_GUARD_CREATE_CONFIG_CACHE=true.

When the config signature changed and config cache exists, the guard takes a file lock and tries:

When the route signature changed and a route cache file already exists, the guard takes a file lock and tries:

If pre-bootstrap rebuilding cannot run because bounded PHP process control or a PHP CLI binary is unavailable, stale config cache is removed and stale route cache is bypassed with a signature-based route cache path. An internal pending marker records the exact pre-bootstrap source signature, then the service provider processes that marker with Artisan::call() after the current HTTP response is sent. This prevents the deferred layer from registering a different signature after Laravel has loaded .env.

What it does not do

• It does not parse, log or store .env values. Content-signature mode may hash .env file bytes in memory without persisting the values.
• It does not persist raw runtime filesystem paths in deployment signatures.
• It does not use Redis, queues, workers, cron or a database.
• It does not require you to manually register middleware.
• It does not expose an unauthenticated public repair endpoint.
• It does not require a secret repair token for automatic in-app repair.
• It does not rebuild config cache or route cache on every request.
• It does not automatically start route caching when your app is not already using route cache.
• It does not run cache:clear, optimize:clear, view:clear or event:clear.
• It does not replace a proper deployment process.

The pre-bootstrap guard is loaded through Composer autoload.files. The package service provider only registers Artisan commands and schedules internal pending repair markers to run after the current HTTP response is sent.

When to use this package

Use it when:

• you deploy Laravel through FTP or shared hosting
• your deploy process sometimes forgets php artisan config:cache or php artisan route:cache
• your hosting panel has limited deployment hooks
• your hosting disables exec(), SSH or direct command access
• you want a small safety net against stale config cache or stale route cache
• you want to avoid queues, Redis, cron or background workers

Do not use it as a replacement for a correct deployment pipeline.

How it works

This order is important. A Laravel middleware or normal service provider is too late to prevent Laravel from loading old cached config or old cached routes. The Composer-loaded guard prevents stale cache from being used. The in-app auto repair fallback only runs after the current response is sent, so Laravel's in-request view, session and routing state is not disturbed by cache rebuild commands.

Installation

That single Composer command is enough for normal Laravel projects. No manual require line is needed in public/index.php.

Optionally verify the integration with:

Upgrading from older versions

Older versions asked you to add a manual require line to public/index.php:

That line is now legacy. It is safe because the guard is idempotent, but it is no longer needed.

Remove it manually, or run:

A dry run is available:

When updating a source checkout or replacing this repository from a ZIP file, replace it in a clean directory instead of extracting over the previous tree. An overlay cannot remove files that were deleted by a newer release. Run composer install and regenerate the optimized autoloader after the clean replacement.

Status check

This checks:

• whether Composer autoload integration is active
• whether a legacy public/index.php require line still exists
• whether the guard is enabled
• whether the config guard is enabled
• whether the route guard is enabled
• whether the in-app auto repair fallback is enabled
• which failure cooldown is configured
• whether fail-hard mode is enabled
• which Laravel bootstrap cache directory is active and whether it is writable
• which config cache path is active and whether it is writable
• whether cached config exists
• whether cached routes exist
• whether the config and route signature files exist
• whether pending repair markers exist and why
• whether failed-rebuild markers exist and why
• when config and route cache repair last succeeded
• which active cache files are currently expected
• how many stale route cache files were cleaned during the last successful route repair
• whether bounded PHP process control is available
• which PHP CLI binary will be used
• which lock and process timeouts are configured

Clear old failure and pending markers after fixing a hosting issue:

Deployment scripts can request a non-zero exit code for unsafe or unresolved states:

Requirements

• PHP 8.2 or higher
• Laravel 12 or 13
• A writable active Laravel bootstrap cache directory (bootstrap/cache or .laravel/cache)
• A writable configured config cache file or parent directory when APP_CONFIG_CACHE points elsewhere
• Optional: proc_open() and a working PHP CLI binary for bounded pre-bootstrap rebuilding

When bounded process control is unavailable, the in-app auto repair fallback can still rebuild through Artisan::call() after the current response is sent.

Compatibility

PHP 8.2 is security fixes only until December 31, 2026. For new production projects, prefer PHP 8.4 or PHP 8.5 when your hosting supports it.

As of August 17, 2026, the non-EOL runtime matrix is PHP 8.2, 8.3, 8.4 and 8.5 with Laravel 12, plus PHP 8.3, 8.4 and 8.5 with Laravel 13. Laravel 13/PHP 8.2 is deliberately absent because Laravel 13 officially requires PHP 8.3 or newer. Security-only support still counts as supported; a version is removed when its official security support ends. composer check:support validates the Composer constraints, dependency pins, platform definitions and compatibility/E2E matrices against tests/Support/policy.php, and deliberately fails once a configured branch reaches EOL or any supported platform/runtime entry disappears.

Useful references:

• PHP supported versions: https://www.php.net/supported-versions.php
• Laravel release support policy: https://laravel.com/docs/13.x/releases

Environment options

The pre-bootstrap guard runs before Laravel loads .env. Therefore every CONFIG_CACHE_GUARD_* override, APP_CONFIG_CACHE, APP_ROUTES_CACHE and APP_ENV value that must affect the guard must be configured as a real process or server environment variable. Putting such an override only in .env is too late for pre-bootstrap detection. Default package behavior does not require extra variables.

At Composer load time, the guard keeps an in-memory snapshot of only these named control and cache-path variables. The status command and deferred repair layer use that same pre-bootstrap snapshot, so a value that appears later through Laravel's dotenv bootstrap cannot silently change guard behavior halfway through the request. Values supplied by the process or web server before Composer loads are preserved for the whole request.

Example process/server environment configuration:

Shared hosting without process control

Some shared hosts disable process functions such as proc_open(). In that case, the pre-bootstrap guard does not start php artisan config:cache or php artisan route:cache before Laravel boots.

This package handles that without a public endpoint:

If no config cache exists at all and you intentionally want the package to create one without SSH or a deployment hook, set CONFIG_CACHE_GUARD_CREATE_CONFIG_CACHE=true as a real server environment value. Otherwise the application continues without config cache until another valid deployment mechanism creates it.

If the in-app repair fails, a safe .failed marker is written in the active Laravel bootstrap cache directory. It contains a reason and suggested action, but no .env values, raw runtime paths, secrets, tokens or command output.

Files written by the guard

The guard may create or update these files inside Laravel's active bootstrap cache directory (bootstrap/cache or .laravel/cache). The actual config cache file can live elsewhere when APP_CONFIG_CACHE is configured:

Failure behavior

Removing stale config cache files is intentional. For routes, the guard avoids stale reads by switching Laravel to a route-cache filename derived from the current route source signature. Explicit custom APP_ROUTES_CACHE paths are respected; if a custom route cache is stale and cannot be rebuilt before boot, the stale file is removed and rebuilt at the same custom path after the response. Running uncached for one request is slower, but safer than continuing with old configuration or old routes.

Testing manually

After installation, you can test the config guard like this:

Then change a value in a file such as config/app.php or update its modified time:

Load the application once in the browser. If proc_open() and PHP CLI are available, the guard should rebuild the active config cache and update config-source.signature in the active Laravel bootstrap cache directory.

If bounded process control is disabled, the first request removes the stale config cache and queues in-app auto repair after the response. A following request should use the refreshed config cache if the repair succeeded.

To test the route guard, first make sure your app already uses route cache:

Then change a route file or update its modified time:

Load the application once in the browser. If proc_open() and PHP CLI are available, the guard should rebuild the active routes-*.php cache and update route-source.signature in the active Laravel bootstrap cache directory.

If bounded process control is disabled, the first request points Laravel at a signature-based route cache path and queues in-app auto repair after the response. A following request should use the refreshed route cache if the repair succeeded.

Recommended production flow

Use this package as a fallback, not as your primary deployment strategy when destination deployment commands are available.

A deployment target that exposes a reliable command runner should still include:

Only run php artisan route:cache in deployments when your application supports Laravel route caching.

On FTP-only/shared hosting where SSH, Terminal or deployment hooks are not available, destination-side Artisan is not a package requirement. Keep the active Laravel cache directory writable and use the documented in-app fallback. See Deployment recipes.

Known limitations

• Pre-bootstrap rebuilding requires proc_open() and a working PHP CLI binary. Commands are invoked without a shell and stopped after CONFIG_CACHE_GUARD_PROCESS_TIMEOUT seconds.
• Lock acquisition is bounded by CONFIG_CACHE_GUARD_LOCK_TIMEOUT, so concurrent or abandoned rebuilds cannot hold a request indefinitely.
• In-app auto repair works without external process control, but it runs after the current HTTP response is sent. The current request runs without stale deployment cache first.
• CONFIG_CACHE_GUARD_FAIL_HARD=true intentionally stops the request with a safe 503 page, so in-app auto repair cannot run during that same request.
• Change detection uses fast metadata signatures by default. Filesystems or deployment tools that preserve timestamps, size and inode metadata for a same-size in-place rewrite can evade that mode. Set CONFIG_CACHE_GUARD_SIGNATURE_MODE=content at process or web-server level to hash source contents, including .env files, without storing their values. Content mode performs more file I/O on every guarded request; a normal deployment cache rebuild remains the primary release mechanism when deployment commands are available.
• Config cache creation when missing is opt-in through CONFIG_CACHE_GUARD_CREATE_CONFIG_CACHE=true.
• Route cache guarding only activates automatically when a routes-*.php file already exists in Laravel's active bootstrap cache directory.
• Pre-bootstrap cache path detection supports Laravel's standard bootstrap directory and Laravel 13's .laravel directory. Arbitrary bootstrap paths selected later through application code cannot be discovered before bootstrap/app.php runs.
• A custom APP_CONFIG_CACHE, APP_ROUTES_CACHE or guard override placed only in .env is unavailable to the Composer-loaded pre-bootstrap guard. Configure these overrides at process or web-server level. The deferred layer intentionally keeps using the earlier external-environment snapshot for consistency.
• The package does not clear application cache, view cache, event cache, OPcache or Redis.
• This package is a fallback safety net. It should not replace a correct deployment pipeline when one is available.

Troubleshooting

The status command says Bounded process control available: no

Your hosting disables one or more required process-control functions. The guard can still remove stale cached config and bypass stale cached routes. With CONFIG_CACHE_GUARD_AUTO_REPAIR=true, it can then rebuild through Artisan::call() after the current HTTP response is sent.

I see config-cache-refresh.pending or route-cache-refresh.pending

A stale cache target was handled and the package queued an in-app repair. Load the application once more, then run:

If the pending marker remains, check whether Laravel can run the relevant cache command.

I see config-cache-refresh.failed or route-cache-refresh.failed

Open the file. It contains a safe diagnostic reason and suggested action. It does not contain .env values, secrets, tokens or command output.

After fixing the issue, clear old markers:

Or remove them manually from Laravel's active bootstrap cache directory.

public/index.php still contains the old require line

Current versions do not need this line anymore:

Remove it manually, or run:

PHPStan still reports RefreshAfterRouteCacheRepair after upgrading

src/Http/Middleware/RefreshAfterRouteCacheRepair.php is not part of the current package. If PHPStan still scans it, an older source file remained because a ZIP was extracted over an existing checkout. Remove that exact stale file or replace the checkout in a clean directory, then regenerate Composer autoload metadata:

On Windows PowerShell, the obsolete file can be removed explicitly before regenerating autoload metadata:

The wrong PHP binary is detected

Set the binary manually:

Then run:

I do not want in-app auto repair

Disable only the in-app fallback:

I do not want route cache guarding

Disable only route cache guarding with a real server environment variable:

I want to disable the guard temporarily

Use a real server environment variable:

Development and quality checks

Install the development dependencies and run the complete local gate with:

composer check is the fast non-Pest quality gate. It validates the date-aware PHP/Laravel support policy, runs strict Composer validation, builds and inspects the package distribution archive, runs the security audit, generates an optimized strict-PSR autoloader, checks Pint formatting and runs PHPStan. composer check:all adds Pest once. The focused commands remain available as composer check:support, composer check:composer, composer check:distribution, composer check:security, composer check:autoload, composer format:test, composer analyse, composer test and composer test:coverage. The coverage command requires Xdebug and enforces the non-decreasing 80% baseline.

Run the real application end-to-end suite before a release:

composer test:e2e runs the full suite by default. It creates temporary fresh Laravel 12 and 13 applications, installs this checkout through a copied Composer path repository, builds real config and route caches, and sends HTTP requests through PHP's built-in server. It verifies bounded pre-bootstrap CLI repair, the process-control-disabled in-app fallback, a custom APP_CONFIG_CACHE path and Laravel 13 with .laravel as its active bootstrap path. composer check:release runs the fast quality gate, Pest, builds a Composer ZIP and installs that exact artifact before running the full E2E suite. The temporary applications are removed automatically. Composer's default process timeout is disabled only for these network-heavy E2E commands.

Use composer test:e2e -- --laravel=12 to run one framework version or add --keep to retain a failing full-E2E fixture for inspection. The CI portability path uses composer test:e2e -- --laravel=12 --suite=smoke: that focused suite fetches the Laravel skeleton with create-project --no-install, resolves Laravel plus this package in one dependency-install phase and validates the platform-sensitive pre-bootstrap stale-config repair path without repeating the full HTTP scenarios.

GitHub Actions deliberately separates runtime compatibility from platform portability:

• Linux x64 runs package tests for every supported PHP/Laravel pair: PHP 8.2–8.5 with Laravel 12 and PHP 8.3–8.5 with Laravel 13.
• Linux x64 runs the full real-application E2E suite on the lowest supported PHP runtime for each Laravel major.
• Windows x64, macOS ARM64, Ubuntu Linux ARM64 and Alpine Linux x64 each start one PHP 8.5 environment, then run Laravel 12 and Laravel 13 package tests plus the focused portability smoke suite in that same environment.
• Separate Linux jobs verify the minimum supported Composer dependency set for Laravel 12 and 13.
• Coverage includes the real pre-bootstrap guard and maintains the 80% minimum.
• Pull requests receive dependency review.
• A stable CI gate combines required results. Intentionally skipped jobs are accepted only when the CI planner classified them as unnecessary for that change.
• Documentation-only pull requests keep the required CI gate but skip the expensive runtime, E2E, portability, minimum-dependency and coverage jobs.
• Runtime, Composer, test, workflow, release and scheduled weekly checks run the full matrix.

Stable releases use a release pull request. A maintainer starts Prepare release PR from GitHub Actions and selects a patch, minor or major increment. The workflow prepares the versioned changelog, opens the release PR, approves the generated test run for that exact release commit and enables auto-merge. The protected branch keeps that merge blocked until the required CI gate passes. After auto-merge, the workflow explicitly starts protected main. The release job only allocates on a normal main push when the changelog diff introduces a newly prepared dated SemVer release, or when main is explicitly dispatched. It then creates the annotated tag, tests the exact release ZIP, uploads its checksum and provenance, creates the GitHub Release and verifies that Packagist exposes the same version and commit. No Packagist token or local signing key is required.

Uninstall

Remove the package:

If you installed an older version that added a manual require line to public/index.php, remove it too:

Optional cleanup for the default Laravel bootstrap cache directory (use .laravel/cache instead when that is the active directory):

Security and privacy

This package is intentionally small and file-based.

• It does not parse, log or store .env values; content-signature mode may hash source bytes in memory.
• It does not persist raw application or canonical runtime paths; config runtime identity is stored only through one-way signature material.
• It does not store secrets.
• It does not send data to external services.
• It does not use a database.
• It does not require Redis, queues, workers or cron.
• It uses file locks to avoid concurrent rebuilds.
• It atomically replaces and verifies source-signature files before a rebuilt cache is accepted as tracked deployment state.
• It keeps only a request-local snapshot of the documented non-secret guard controls and cache paths; it does not snapshot arbitrary environment variables.
• The automatic rebuild commands are fixed argument arrays for php artisan config:cache and php artisan route:cache; no shell is invoked and no user input becomes a command argument.
• The in-app auto repair fallback uses Laravel's own Artisan::call() and does not expose command output.

Please report security issues privately. See SECURITY.md.

License

The MIT License. See LICENSE.md.

About Codegenie

Codegenie builds Laravel websites and web applications with a focus on simplicity, reliability and production-friendly deployment.

https://www.codegenie.be