Bug Catcher Reporter Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for error tracking. The reporter bundle is the client half of a self-hosted error-tracking stack for Laravel/PHP: exceptions captured in-app, serialized as Codeframe[], rendered in the Bug Catcher UI. This release doesn't change that positioning — it improves the fidelity of what you already own — so it's evidence for the "build/own it" side of the ledger rather than a reason to revisit the decision.
• Observability roadmap sequencing. v2.1.1 closes a long-standing accuracy gap (throw site missing from the first frame, previous-exception chain dropped). If "make production debugging trustworthy" is a roadmap theme, this is a cheap, low-risk increment to bank now and cite as delivered.
• MTTR as a success metric. The two fixes target exactly what determines time-to-root-cause: the first frame being the caller rather than the throw site, and the Caused by: chain being absent so engineers reason about symptoms instead of causes. Worth tracking before/after on a sample of recent incidents.
• Support-to-engineering escalation cost. The greedy-regex fix is a real support-quality item: messages containing (1064): (classic SQL syntax errors) previously swallowed the real file and line, producing a frame pointing at the wrong place. Fewer "can you tell me where this actually came from?" round-trips.
• Release coordination and version skew. The Caused by: labels require the matching server-side template change (bug-catcher/bug-catcher#19). Without it, extra frames still render — just unlabeled. That's a product decision about whether partial value ships now or you hold for a coordinated release.
• Upgrade policy / maintenance-window planning. Drop-in: no new config keys (stack_trace already defaults to true), no service bindings or constructor signatures touched, wire format unchanged. Existing records are untouched because frames are parsed client-side at write time. That makes this a "slot into the next maintenance window" decision, not a project.

When to Consider This Package

Consider it when:

• You run Laravel/PHP services and want exception reports with code frames and stack context landing in a system you operate, not a per-seat SaaS.
• You already run (or intend to run) a Bug Catcher server; this bundle is the reporting side and is only half the product without it.
• You already log through Monolog — BugCatcherMonologHandler integrates there, and this release makes the Monolog path use the real Throwable when context['exception'] carries one, falling back to the formatted string otherwise.
• Data residency, vendor-spend, or procurement constraints make a hosted error tracker awkward.
• You value trace accuracy over breadth of platform features — this release is squarely an accuracy investment.

Look elsewhere when:

• You need turnkey alerting, release health, crash-free-session tracking, issue grouping/deduplication, or AI summarization out of the box — that's Sentry/Bugsnag/Rollbar/Flare territory, and the in-house path means you own the dashboard and its backlog.
• You need a single vendor covering browser/mobile/backend SDKs and APM (traces, metrics) alongside errors.
• You have no appetite to operate the server side, or no maintainer for the UI — note that a labeling improvement here requires a separate server-side change, which is a small but real signal about cross-repo coordination overhead.
• Your errors are predominantly non-PHP (JS, mobile) — this package won't move the needle there.

How to Pitch It (Stakeholders)

For executives (one paragraph). We can improve how quickly engineers diagnose production incidents at effectively zero cost and zero migration risk. Version 2.1.1 of our error-reporter bundle fixes two accuracy defects that have been sending engineers to the wrong line of code: the first stack frame was the caller instead of the actual throw site, and chained/cause exceptions were being discarded entirely. It's a drop-in patch — no configuration changes, no schema or wire-format changes, existing reports unaffected — so it can ride the next maintenance window. No new vendor spend, and error data continues to stay in our own infrastructure.

For engineering (the substance).

• What was broken. BugCatcher::logException() fed getTraceAsString() into the frame parser, but that string's #0 is already the caller of the throwing frame — the real position only exists in getFile()/getLine(), which that path never read. Separately, the Monolog path's synthetic #0 file(line): message line was parsed with a greedy /#\d+ (.*)\((\d+)\): (.*)/, so any message containing something like (1064): hijacked the file/line capture.
• What changed. New ThrowSiteStacktrace builds the first Codeframe directly from the Throwable, reusing the vendor parser's code-window extraction so context lines match the parsed frames. It also walks getPrevious(), which ErrorFormater used to drop, labelling those frames Caused by: .... CollectCodeFrame gains collectThrowableFrames(Throwable); collectFrames(string) remains as fallback. WriteStackTraceListener always uses the new path; BugCatcherMonologHandler uses it whenever context['exception'] is a Throwable.
• Upgrade risk. Low. Drop-in, no new config keys, no constructor signatures touched, wire format still serialize(Codeframe[]) so no server-side change is required. Existing records unaffected — frames are parsed client-side at write time.
• One coordination item. The Caused by: labels need the matching server-side template change (bug-catcher/bug-catcher#19). Frames appear either way; without the template change they're just unlabeled. Recommend scheduling both together so the feature reads as intended in the dashboard.

The ask. Approve the v2.1.1 bump for the next maintenance window, and pair it with deployment of the server-side template change so the cause-chain labels land in the same release.