Laravel Static Laravel Package

Technical Evaluation

Architecture fit. backstagephp/laravel-static sits in the response path as a full-page static cache for Laravel: it writes one file per URI including the query string to a local disk and serves those files directly. That design fits anonymous, highly cacheable, content-driven workloads — marketing sites, docs, blogs, landing pages handed around with campaign links. It does not fit authenticated, personalized, or high-cardinality-query applications, where per-URI file proliferation is guaranteed.

v0.11.0 is an observability release, not a control release. static:status reports storage split by query-string vs. non-query-string URLs, du-style directory rollups with pass-through levels collapsed, top URLs by variant count, most common query parameters, per-host and per-file-type breakdown, age distribution, largest files, and the governing config settings on one screen. --disk=, --limit=, and --json make it scriptable. Notably it is read-only: nothing in this release adds eviction, TTL, or LRU. The only remediation lever named, static:clear --only-with-query-strings, is a blunt instrument.

Integration feasibility. High. Standard Artisan command, no migrations, no new runtime dependency, JSON output for automation. The only new coupling introduced is --json as a de facto monitoring contract.

Technical risk.

• Unbounded growth is architectural, not incidental. Per the release notes, nothing is removed except by a full static:clear. v0.11.0 makes growth visible; it does not bound it.
• The pruning lever is content-blind. static:clear --only-with-query-strings cannot distinguish ?utm_source=newsletter from ?page=2, ?sort=price, or ?filter=red. Pruning all query-string variants risks serving stale-or-wrong content or 404s for legitimately distinct pages. This is a correctness risk, not merely a cache-miss cost.
• Pre-1.0 stability. At 0.x, the --json schema and command semantics may change between minor releases; treat the JSON contract as unstable until 1.0.
• Traversal cost unquantified. The notes claim memory scales with distinct URL paths rather than file count, but give no wall-clock or IOPS figure for a million-file cache — exactly the case the feature exists for.
• Local disks only. Remote/ephemeral storage (S3, network mounts, container scratch volumes) is out of scope; on such deployments the report will be empty or misleading.

Key questions for the maintainer.

1. Is TTL- or allow/deny-list-based variant pruning on the roadmap, as opposed to the current all-or-nothing query-string clear?
2. Is the --json payload versioned, and what is the stability commitment?
3. What is measured runtime and memory on a 1M- and 10M-file cache?
4. Why is query-string cardinality addressed post-hoc at prune time rather than at write time via parameter normalization or tracking-param stripping in the cache key?
5. How does this interact with CDN/Vary strategy — are we caching twice?

Integration Approach

Stack fit. Standard Composer package with Laravel auto-discovery and publishable config; requires a writable local filesystem with inode headroom and web-server rewrite rules (nginx try_files / Apache) to serve the static files. Confirm the supported Laravel/PHP matrix against the composer constraints before committing.

Migration path. Additive if the application currently has no full-page cache, or uses a CDN-only strategy. It is not a drop-in replacement for cache-store-based FPC packages (e.g. response-cache implementations backed by Redis/Memcached): this package writes files, so invalidation cannot be done with Cache::forget(). Teams migrating from a store-backed cache must rebuild their invalidation story around static:clear, which only supports coarse-grained clearing.

Compatibility. Two deployment shapes need explicit handling: (a) multi-node fleets — run static:status per node or against a shared volume using --disk=; the numbers are per-disk, not per-cluster; (b) containerized/ephemeral filesystems — the command will report near-zero and create false confidence that the problem does not exist.

Sequencing.

1. Pin the exact version in composer.json; do not float on ^0.11.
2. Deploy to staging, capture static:status --json as a baseline.
3. Schedule the JSON output into monitoring/alerting for one to two weeks to establish a real growth curve before touching policy.
4. Only then define a pruning policy — prefer TTL or an allow-list of "safe to prune" parameters over --only-with-query-strings.
5. If the blunt clear is used, gate it behind a reviewed runbook entry, never a cron job.

Operational Impact

Maintenance. Pre-1.0 and fast-moving; assume breaking changes in minor versions. Pin, review changelogs on every bump, and keep the upgrade surface small by not building bespoke tooling on the --json schema without a version check.

Support. Community/upstream only; no vendor SLA. The team will need its own runbook for the two predictable incidents: "disk/inode exhaustion" and "status command is slow on the big cache."

Scaling. The diagnostic is explicitly designed for multi-million-file caches, but the underlying design has no eviction. Growth is a direct function of distinct query strings, which bots, newsletter links, and ad platforms generate without bound. Plan for disk exhaustion, inode exhaustion, and degraded directory-listing performance as the realistic ceilings. static:status converts this from a surprise into a known quantity — it does not remove the need for a policy, and a policy needs an owner.

Failure modes.

• Disk or inode exhaustion (primary, and the reason this release exists).
• Wrong content or 404s after a blanket query-string clear removes legitimate variants.
• Stale pages with no targeted invalidation path.
• Misleading empty reports on ephemeral or remote volumes.
• Alert fatigue if --json thresholds are wired up without a tuned baseline.

Ramp-up. Low for execution — any engineer can run the command and read the summary in minutes. Moderate for interpretation: deciding that "35% of cached pages are URL variants of 11 distinct URLs" is a routing/query-semantics question specific to the application, and choosing between TTL, allow-list, or blunt clear is a judgment call. Budget roughly half a day of a senior engineer to define the policy, plus a short monitoring hookup.

Overall. No prior assessment existed; this establishes the baseline. v0.11.0 is a genuinely useful operational addition that materially improves diagnosability and is worth adopting for that reason alone. It does not address the root cause — unbounded, never-evicted cache growth — and it ships alongside a remediation command with real correctness risk. Recommendation: conditional adoption — take the status/monitoring capability now, defer automated pruning until a TTL or allow-list mechanism exists or the team has explicitly validated which query parameters are safe to discard.