Laravel Monitor Laravel Package

Getting Started

This is a Quiet-Guard error/exception monitor for Laravel: it captures what went wrong, but the interesting part is what leaves your app — request context, headers, URL, logs — and how it is masked. Treat the config file as the primary API.

1. Install the client; it pulls in the core (quiet-guard/core) as ^0.6.0. Upgrade the two together — PayloadBuilder calls Scrubber::masks() and reads ValueRedactor::CREDENTIALS from the core, so a mismatched pair fails at payload-build time, not at install time.
2. Publish the config and read it end to end before wiring credentials. The three keys that matter day to day are:
   • monitor.request_headers — the allow list of header names whose values travel in clear.
   • scrub — names (headers, query params, route parameters) that are masked.
   • redact — the credential class list; null in a freshly published file means "follow the package defaults".
3. Point it at a project (env credentials) and deploy to staging first.
4. First use case: let the framework handler report unhandled exceptions untouched, then open one report and audit it field by field against the real request. That audit — not the dashboard — is how you learn this package.

Where to look first when something is wrong: PayloadBuilder (what is assembled), Transport::redact (the final cut), and the core's ValueRedactor (shape-based masking). Everything else is plumbing.

Implementation Patterns

Zero-touch exception reporting. The default integration reports unhandled exceptions and logged errors with no per-callsite code. Keep it that way; reach for manual reporting only for handled-but-interesting failures (payment declines, third-party 5xx after retries).

Default-deny headers, opt-in values. Since v0.6.0 every header travels by name; only the allow-listed ones carry a value, everything else is [scrubbed]. The default list is deliberately boring (accept, content-type, host, origin, user-agent, x-requested-with, x-livewire, x-inertia, x-inertia-version, plus encoding/cache/length). If your app relies on a tracing header (x-request-id, traceparent), add it to monitor.request_headers — but only if you are certain the value is not a secret. The allow list is an exposure list, not a safety list.

IP capture when you have a legal basis. The six visitor-IP headers are absent from the allow list by design. To capture them, add them to monitor.request_headers and remove them from scrub — the scrub list applies on top of the allow list, so leaving them in scrub masks them anyway. Note forwarded masks x-forwarded-for by substring: if you whitelist x-forwarded-for, also drop forwarded from scrub, or you will capture nothing and spend an afternoon confused.

Signed-URL and reset-token coverage. Route parameters are masked by name when scrub matches (token, hash, signature), which covers /reset-password/{token} and Laravel's own /email/verify/{id}/{hash} regardless of length. The old shape rule (forty letters/digits) remains as a safety net. Add your own parameter names to scrub — the name rule is the reliable one.

Queue-safe by construction. Reports dispatched to a queue are masked before dispatch, so the queued path and the sync path produce identical payloads. This means masking config changes take effect on the next build: after editing scrub, redact, or request_headers, re-run config:cache and restart queue workers, or you will be comparing old and new reports.

Customising PayloadBuilder. It takes a sixth constructor argument — the headers sent in clear — where null falls back to PayloadBuilder::HEADERS. Binding a subclass with five arguments therefore still works and inherits the defaults; passing a list explicitly is how you widen exposure for one specific reporter.

Log collection. LogCollector feeds context/message text into the same pipeline (same soft-cut, same masking). Useful for correlating a report with surrounding log lines; just remember log lines are user-influenced text and get shape-redacted, not guaranteed-clean.

Gotchas and Tips

• Custom headers silently vanish. Anything not on the allow list arrives as [scrubbed]. This is the intended failure mode, but it looks like a bug the first time your x-tenant-id disappears.
• Never allow-list a credential. The allow list sends values in clear by design; masking happens elsewhere. If you would not paste the header into a ticket, do not list it.
• Truncation is now two-stage. Messages are soft-cut at a whitespace past 8192 chars, masked whole, then hard-cut to the limit — this exists so a token straddling the boundary cannot leak its first half. Do not assume you get the full message; do assume partial tokens are not a leak vector.
• Huge request contexts are replaced, not scanned. Past 65 535 bytes the context is swapped for the server's marker before masking. Large multipart/upload requests produce sparse reports — that is deliberate, not data loss to debug.
• Route masking fails open. URL masking reads $request->route() and falls back gracefully on anything unexpected. Shape-based redaction still applies, but name-based masking may not — do not treat it as a hard guarantee for exotic route bindings.
• Published config is version-sensitive. A copy published before v0.6.0 carrying ['email', 'iban', 'nir', 'card', 'phone'] is read as the old default and still masks credentials. Fresh installs get 'redact' => null, which tracks the package and names no class of it — so removing the package never leaves a fatal config file. Prefer null and let the package own the list; only pin an explicit array if you have a compliance reason, and expect to maintain it.
• Shape redaction is a net, not a proof. Emails, IBANs, cards, phones, and credentials are caught by pattern, including inside fullUrl() (percent-encoded query and path segments are decoded before matching). A secret that looks like nothing in particular still travels. Pair this with not logging secrets in the first place.
• Extension points: the PayloadBuilder constructor argument for headers, the scrub list for names, and the core's ValueRedactor/Cut classes for shape and truncation behaviour. Override at the top (PayloadBuilder) rather than patching the transport — Transport::redact is the last line of defence and you want it boring.
• Debugging what actually goes out: build a payload in a test or tinker session against a fixture request and read the array, instead of inferring from the UI. The config tells you intent; the payload tells you the truth.