Laravel Static Laravel Package

Technical Evaluation

Architecture fit. static:status is an additive, read-only Artisan command in backstagephp/laravel-static, a package that caches rendered pages to disk as one file per URI (query string included). It introduces no new runtime dependency, no schema, no service, and no change to the caching path itself. It is best understood as an observability surface bolted onto the package's existing storage layer: it walks the cache directory and reports size distribution, URL/variant cardinality, top query parameters, per-host and per-file-type breakdown, age distribution, and the config values that govern growth. For any team already running this package in front of a Laravel app, fit is essentially zero-friction. For teams not running it, this release is not a reason to adopt.

Integration feasibility. Low effort, two distinct integration targets:

• Human path: engineers and on-call run the command manually during incidents or audits. --disk= and --limit= make it safe to scope to a directory or cap output for a quick look.
• Machine path: --json is the lever that matters for a TPM. It converts cache disk usage from an opaque, discover-by-outage quantity into a schedulable, alertable metric that can be scraped by an existing monitoring stack without building a bespoke exporter.

The command also surfaces the levers (config settings governing cache growth) alongside the numbers, which shortens the loop from "disk is filling" to "here is the setting to change."

Technical risk. Predominantly operational rather than code risk:

1. Filesystem walk cost. A du-style traversal of a cache with millions of files is real I/O. Running it against a live production disk at peak is a plausible self-inflicted latency incident. Schedule off-peak or run against a replica.
2. Local disks only. Remote disks (S3, and by extension most cloud object-store or network-mounted cache backends) are explicitly unsupported — deliberately, to avoid one API call per file. Any team whose cache lives on shared or object storage gets no coverage from this command, and a failure here may present as an empty or trivial report rather than an error. That is the most dangerous failure mode in the release.
3. Pre-1.0 instability. A 0.x package carries no semver guarantee. Command name, flags, and --json shape may all change under you.
4. Diagnostic, not remediation. The command makes a symptom visible. The underlying cause — uncapped query-string variant explosion from utm_*, fbclid, and similar — is a caching policy problem. Pruning with static:clear --only-with-query-strings reclaims space but does not stop recurrence; the durable fix is normalization or exclusion at cache-write time, or at the CDN/edge.
5. Memory claim is scoped. "Scales with distinct URL paths rather than files" is reassuring for multi-million-file caches, but pathological path cardinality (rather than file cardinality) is the untested edge.

Key questions.

• Is the --json output schema versioned or otherwise contractually stable? Can we depend on it in a monitoring pipeline across minor upgrades?
• Is static:clear --only-with-query-strings new in v0.11.0, or pre-existing? The release notes reference it as remediation without listing it under "What's new" — we need to know the minimum version that supports our runbook.
• Is there a supported way to prevent query-string variants from being cached (config ignore rules, canonicalization), or is periodic pruning the intended pattern?
• What is measured runtime on a 1M / 10M-file cache, and does memory hold at high distinct path counts as well as high file counts?
• Does the walk follow symlinks, and is it safe on NFS or other network-mounted local-ish filesystems?
• How does the command behave on an unreadable directory or a mismounted --disk path — hard error, or silent partial report?
• Is there a host filter beyond --disk/--limit for multi-tenant or multi-host cache layouts?

Integration Approach

Stack fit. Drop-in for any Laravel application on a supported PHP version already using the package for full-page or static caching. It slots naturally next to the existing static:clear maintenance job and requires no application code changes. There is no coupling to queue, session, or auth subsystems.

Migration path. None required — this is additive tooling, not a data or API migration. The only "migration" is procedural: an existing scheduled static:clear job should be reviewed, because the whole point of this release is that unconditional full clears may be masking a variant-explosion problem that a targeted prune would handle better. Treat that review as an explicit task, not an assumption.

Compatibility. Two concrete checks before rollout: (a) confirm the --json flag exists on the versions in use across all environments so scripts do not silently degrade to human-readable output; (b) confirm --only-with-query-strings availability before writing it into a runbook. Pin the package version in the monitoring job's environment so a 0.x bump cannot break an alert silently.

Sequencing.

1. Run static:status manually in staging against a production-like cache to get a baseline and validate runtime cost.
2. Run once against production off-peak, capture the report, and share it with the team — this is the artifact that justifies any follow-on work.
3. Wire --json into a daily (or hourly, if growth is fast) scheduled job emitting a disk-usage metric and a variant-ratio metric.
4. Set thresholds from the baseline, not from intuition. Alert on variant ratio (cached pages vs distinct URLs) as well as absolute size — ratio is the leading indicator, size is the lagging one.
5. Decide and implement the query-string policy: prefer prevention at cache-write time; fall back to a scheduled --only-with-query-strings prune as containment.
6. Re-baseline after the policy change so the alert thresholds reflect the new normal.

Operational Impact

Maintenance. Near-zero. One command, no migrations, no new infrastructure, no persistent state. The real maintenance burden is the monitoring job — a small script plus a threshold — and the discipline to revisit thresholds after cache policy changes.

Support. A runbook is required, and it should define the vocabulary explicitly: files (includes gzip/brotli siblings), cached pages (logical entries, siblings excluded), and distinct URLs. The command deliberately counts compressed siblings toward size but not toward page count so that enabling gzip does not read as cache growth — good design, but on-call will misread it unless the runbook says so. Without that, expect false "cache doubled" alarms immediately after enabling compression. Also document the local-disk-only constraint, because a misconfigured --disk on an object-store-backed cache produces a reassuringly small report rather than a failure.

Scaling. Runtime scales with file count; memory scales with distinct URL paths. For a large cache this is a minutes-long job, not a sub-second one — schedule accordingly, and use --limit for interactive checks. At multi-million-file scale, monitor the job itself (duration, exit code, output size) rather than assuming it completes; a job that times out and is quietly ignored is worse than no job.

Failure modes, roughly in order of severity:

• Silent under-reporting on remote or misconfigured disks — the most dangerous, because it produces false confidence.
• Unbounded variant growth continues because the command only reports; teams that add monitoring without acting on the parameter table will watch the problem get worse with better dashboards.
• I/O contention from running the walk during peak traffic.
• Script breakage from an unannounced 0.x change to the --json shape, surfacing as a missing metric rather than an error.
• Alert fatigue from thresholds set before a baseline exists.
• Wrong-disk inspection in multi-host or multi-tenant layouts where several cache roots exist.

Ramp-up. Low for individual engineers — one command, readable output, --json for automation. Materially higher for the organization, because this release introduces both a new shared vocabulary and an implicit policy decision (do we cap query-string variants, and where?). That decision needs a named owner; it is exactly the kind of "diagnostic shipped, remediation deferred" gap where a TPM adds value. The framing to bring to stakeholders: this release converts cache disk usage from a reactive incident class ("disk full at 3am") into a measurable service-level indicator with a leading indicator attached, and the follow-on policy work is where the actual cost avoidance is realized.