amjadiqbal/kiln
amjadiqbal/kiln is a Laravel/PHP package that provides a lightweight, framework-friendly utility for common development tasks. It installs via Composer and offers a simple API for quick integration into Laravel applications with minimal configuration.
Kiln is a small, dependency-free toolkit for the part of a Laravel deploy that everyone forgets: OPcache. Install it like any other package (composer require amjadiqbal/kiln) and let package discovery register the service provider, then publish the config file before you touch anything (php artisan vendor:publish --provider="Amjadiqbal\Kiln\KilnServiceProvider" — confirm the actual provider/tag with php artisan vendor:publish and pick the Kiln entry).
Read the config file first. It is where the HTTP route is toggled (disabled by default) and almost certainly where the warm path list and route prefix/signature settings live. That file is your map for everything else.
Then, in a production-representative environment, run these in order:
php artisan kiln:config — safe, read-only, and the highest-value command on day one. It dumps the OPcache ini directives that matter and flags risky combinations. Treat anything it flags (most commonly opcache.validate_timestamps=1 in production) as a discussion item, not an automatic fix.php artisan kiln:status — but read the output with the SAPI caveat in mind (see Gotchas). Under the CLI SAPI this is usually not the OPcache your users hit.php artisan kiln:warm — only meaningful if opcache.enable_cli=1; otherwise use the HTTP route.The first real use case is a deploy pipeline step: after the release is live (symlink switched, config:cache/route:cache/event:cache rebuilt), invalidate and re-warm OPcache inside the FPM pool, then assert kiln:status looks sane. Start with kiln:config in CI as a non-blocking advisory check, and promote it to a hard failure only once you know your baseline.
Deploy pipeline: clear → warm → verify. Clear first, warm second. Warming a file that is already cached with validate_timestamps off will not recompile it, so a warm-only deploy can leave stale bytecode in place. A typical release script step:
php artisan kiln:config # advisory or gating, see below
# release is now live
curl -fsS "$KILN_CLEAR_URL" # signed URL, short TTL
curl -fsS "$KILN_WARM_URL"
curl -fsS "$KILN_STATUS_URL" | jq '.memory_used, .hit_rate'
Note there is no bundled HTTP client — you drive the route with whatever your pipeline already has (curl, your CI provider's HTTP step, an Ansible uri task). This is deliberate: the package does not add Guzzle to your app just for deploys.
Signed-route pattern. Enable the route in config only outside local, put it behind Laravel's signed middleware with a short TTL, and serve it over HTTPS only. Generate the URL in the deploy job rather than storing a static one — a php artisan helper command of your own that wraps URL::temporarySignedRoute(...) and echoes the URL is the cleanest way to bridge "deploy script" and "Laravel knows the APP_KEY". Avoid long-lived or non-expiring signatures; the URL is a bearer token in your CI logs.
Multi-server / multi-pool. OPcache is per-process-shared-memory, per-pool. Loop over every web host in the load balancer and hit each one's route. Sequential is fine for small fleets; if you parallelise, expect a brief hit-rate dip and a burst of recompiles — schedule it during low traffic or accept the cold-start cost. If you run separate FPM pools (e.g. per-tenant), each needs its own invocation.
Config gate in CI. Run kiln:config as a step and fail the build on risky combinations if the command exposes a non-zero exit code for them — verify this, because many such commands only print warnings. If it doesn't, parse the output or keep it advisory and rely on review.
Local development. Leave the route disabled (that's the default) and don't bother warming: OPcache is typically off or per-process in CLI. If you set opcache.enable_cli=1 for a CLI-heavy workload (queue workers, long-running commands), kiln:clear becomes genuinely useful between deploys — but it only affects that process.
Immutable containers. If you build a Docker image per release, the more robust pattern is baking OPcache state at build time (or using opcache.file_cache) rather than warming at runtime. Kiln still earns its keep for kiln:config auditing and for the status endpoint when you need to answer "is this container actually caching anything?" after a rollout.
Queues and Octane. Separate processes, separate OPcache. Warming the web pool does nothing for queue:work or an Octane worker; if those matter, run the clear/warm against them too (for Octane, your restart flow is the natural hook).
php artisan process cannot reach FPM's shared memory. kiln:status on the command line reports the CLI's OPcache, which is usually disabled or empty — do not conclude "caching is broken" from that output. The route runs inside an actual FPM worker, so it's the only honest view of production.opcache.validate_timestamps=0, opcache_compile_file on an already-cached path is a no-op. Warm-only deploys silently keep old bytecode. Related: validate_timestamps=0 is fast but means you must clear on every deploy — make that a pipeline invariant, not a habit.opcache.restrict_api will make the package's opcache_* calls fail (or be silently ignored) if the ini value doesn't match the calling script's path. If commands return "no data" or do nothing on a host that clearly has OPcache on, check this directive before anything else.kiln:warm compiles everything configured; a large codebase can exhaust opcache.memory_consumption or overrun opcache.max_accelerated_files, producing restarts or a cache that evicts as fast as you fill it. Always check kiln:status after the first warm on a real host, and tune those two directives from evidence rather than guesswork. Raising max_accelerated_files above the next prime in OPcache's internal set is wasted — pick from the documented values.max_execution_time or your proxy's timeout, leaving the pool half-warm and the deploy script reporting failure. Batch the warm (e.g. split your path list and call the route per batch) or accept chunking semantics; verify the route reports what it compiled rather than assuming success.php artisan route:cache has already run, the route won't exist until you rebuild the cache. Order matters in the deploy: cache routes, then confirm the route is reachable.APP_KEY and URL host/proxy config. Behind a load balancer, TrustProxies misconfiguration changes the generated host/scheme and signatures will fail with 403 in ways that look like "the package is broken". If you get 403s, check the URL Laravel generates versus the URL CI calls.kiln:config's risk flags are advisory heuristics. Treat a warning as a prompt to check your own constraints (long-running workers, shared hosting, zero-downtime symlink deploys) rather than a rule to apply blindly — e.g. enabling validate_timestamps to silence a warning trades deploy-time clears for per-request stat calls.php artisan kiln:config and php artisan list kiln will answer most of them in under a minute).How can I help you explore Laravel packages today?