Laravel Laravel Package

Getting Started

This release is v1.20.0 — no API-level breaking changes, but it fixes several check behaviours that had been silently permissive or noisily false-positive, so existing installs can upgrade but should expect some results to change. It remains a diagnostics/health-check package: it runs a set of named checks (e.g. missing-error-tracking, asset-cache-headers, xss-vulnerabilities, phpstan, debug-mode, config-outside-config) against your app and reports findings with severities.

1. Install the package and publish its config (php artisan vendor:publish), then open the config file — that is the single most important place to look, since it enumerates every check and its severity.
2. Before treating new results as regressions after upgrading, re-read your config: phpstan now passes 'max' through to PHPStan (it previously ran at level 5 regardless), so anything configured at max will get much stricter. Likewise xss-vulnerabilities now warns when it can't reach the origin rather than passing.
3. Run the package's diagnostic artisan command against a real app (not a fresh skeleton) so you see meaningful output.
4. First use case: run it locally on a project you're about to deploy and fix anything reported at High. missing-error-tracking is the highest-value early win — it tells you production exceptions are going into the void, and it now reads Nightwatch flags from the process environment too, so CI-set env vars are respected.

Implementation Patterns

CI gate. Run the diagnostic command in your pipeline and fail the build on High-severity findings. This is where the package earns its keep day-to-day: it catches drift (a removed Sentry package, a broken asset URL) before it reaches production, without anyone remembering to check. Note that xss-vulnerabilities now emits a warning (not a pass) when it can't reach the origin, so if you gate on warnings as well as Highs, treat that as a real signal rather than noise.

Environment-aware configuration. Disable or downgrade checks that don't apply locally (e.g. asset/CDN checks are meaningless on a dev machine), and keep the full set enabled in staging and production. Keep one config file with per-environment overrides rather than separate configs. Be careful to keep the phpstan level aligned between local and CI so a max setting doesn't suddenly surface a flood of errors in only one place.

Dependency hygiene for missing-error-tracking. Because the check is strict about require-dev (see Gotchas), decide explicitly where your tracker lives: Sentry/Flare/Inspector/Nightwatch belong in require if production ships them. If you only ever use a tracker in local dev, disable the check rather than leaving a permanent warning. Since v1.20.0 the Nightwatch detection also reads the process environment, so trackers configured via CI env vars are now picked up instead of only .env entries.

Custom checks. When you have an invariant specific to your app (queue worker reachable, storage disk writable, a config value non-default), extend the package's base check class and register it in config. Keep these small and side-effect free — they run on every invocation. If a check needs to probe a URL that lives behind a same-host redirect, use OriginReachabilityChecker::probeFollowingSameHost(), which follows same-host redirects and returns a RedirectChain — that is the intended extension point rather than hand-rolling redirect logic.

Asset URL correctness in non-standard setups. If you serve assets from a CDN or a separate host, set app.asset_url (or app.mix_url for Mix projects). asset-cache-headers probes those URLs instead of blindly using app.url, so CDN-fronted apps get accurate results rather than false passes. The same reachability machinery now backs xss-vulnerabilities — an off-host redirect (e.g. Cloudflare Access login) is no longer graded as if it were your app's CSP.

Scheduling. If the package exposes a dashboard or scheduled run, put it on a schedule and route notifications to the team channel that actually acts on them. Unread health dashboards are worse than none.

Gotchas and Tips

• phpstan 'max' now actually means max. This is the biggest upgrade surprise: if you had 'max' configured, earlier versions silently ran at level 5, so your pipeline was greener than it should have been. Upgrade and you'll likely see a large spike in errors that were always there. Decide between fixing them or lowering the level deliberately, and align local/CI configs first. Relatedly, an unsupported level (e.g. 10 on PHPStan 1) is now explained before PHPStan starts rather than failing opaquely.

• require-dev trackers no longer satisfy missing-error-tracking. If you previously had Sentry/Flare/Inspector/Nightwatch in require-dev and the check passed, it will flag you. That's the intended fix — a dev-only dependency isn't installed in production — but it will surface as a new warning on upgrade. Move the package to require or disable the check deliberately.

• Nightwatch flags are now read from the process environment, not just .env. If you were seeing a stale "no error tracking" warning in CI, it may simply have been that NIGHTWATCH_* was set in the pipeline env rather than in a .env file. v1.20.0 fixes that; if the warning persists, verify the vars are actually exported to the process running the command (not just defined in a CI secrets UI).

• The tracker list grew. Flare, Inspector and Nightwatch are now recognised alongside the previously supported trackers via DetectsErrorTracking. If you wrote a custom check that hardcodes a tracker list, reuse the shared trait instead so you don't fall behind future additions.

• xss-vulnerabilities now warns instead of passing when the origin is unreachable. Previously an unreachable origin would slip through as a pass. A suddenly-reported warning could be a genuine reachability problem (firewall, VPN, wrong host) rather than a regression in your app. Also fixed: an off-host redirect (Cloudflare Access login) is no longer graded on its own CSP. Audit your severity threshold if you gate on warnings.

• asset-cache-headers severity changed from High to a warning when an asset can't be fetched. An unfetchable asset in production usually means a bad build, a missing deploy step, or a wrong asset host. Treat the warning as a real signal in CI even though it no longer fails the run — and check your severity threshold if you gate on High.

• Asset probing respects app.asset_url / app.mix_url. If those are set but point somewhere wrong (stale CDN hostname, missing trailing slash), the check will fail against the wrong host. Verify them alongside app.url when debugging.

• config-outside-config changed in both directions. It now ignores an environment marker that only appears in a subdomain (dev.to is no longer flagged), but it now does report hosts on the reserved .test, .localhost and .local TLDs. Expect the reported list to shift after upgrade, and don't assume every old entry was a true positive.

• debug-mode is less noisy. print_r() / var_export() returning their value (rather than printing it) and debug_backtrace() are no longer reported, since they don't emit output. If a check you used to see is silently gone, that's why — don't mistake it for the check being removed.

• Clear config cache after editing config (php artisan config:cache). A cached config silently ignores your check/severity changes and is the most common "why didn't my change take effect" cause.

• Pin the version in CI-sensitive projects. Minor bumps here change check semantics (this release changes phpstan strictness and xss-vulnerabilities reachability reporting), so a lockfile bump can turn a green pipeline red without any application change.