Reporter Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for error tracking. This package is the client-side half of a self-hosted error-reporting stack (Bug Catcher). It informs the recurring "do we pay Sentry/Bugsnag/Flare, or run our own?" question — the answer now leans more favorably toward self-hosting because the debugging fidelity gap just narrowed.
• Adoption/upgrade of the reporter in existing Laravel services. v2.1.1 is a drop-in patch: no config keys, no service bindings, no constructor changes, no server-side wire-format change. That makes "upgrade across all PHP services" a low-risk, low-cost roadmap item rather than a migration project.
• Incident response / MTTR investment. The release fixes a correctness bug where the top stack frame was the caller rather than the throw site — a one-frame-off error that sends engineers to the wrong file. It also surfaces chained exceptions (getPrevious()) that were previously dropped entirely and are now labelled Caused by: …. For Laravel apps, where a QueryException typically wraps a PDOException, this is the difference between seeing the real root cause and seeing a wrapper.
• Observability roadmap sequencing. Because the Caused by: labels require a matching server-side template change (bug-catcher#19), this release creates a small client/server version-coupling item that belongs on the platform roadmap alongside the reporter upgrade.
• Prioritization of internal developer tooling. Accurate codeframes with context lines are a developer-experience feature with measurable impact on triage time — useful evidence when arguing for tooling investment against feature work.
• Data residency and vendor-risk posture. Choosing a self-hosted reporter keeps production stack traces inside our own infrastructure, which supports compliance and procurement decisions independent of feature parity.

When to Consider This Package

Consider adopting when:

• The stack is Laravel/PHP and exceptions already flow through Laravel's handler and/or a Monolog handler — the package hooks both paths, so integration cost is near zero.
• The team is small enough that "open the dashboard, read the throw site" needs to be the whole workflow; there is no budget or headcount for a full APM rollout.
• Self-hosting is a requirement or a strong preference (data residency, cost, air-gapped environments).
• The team wants exception grouping and code context, not distributed tracing, span metrics, or session replay.
• Willingness exists to run and upgrade the Bug Catcher server component alongside the client bundle — the two versions must be coordinated for full feature display.

Look elsewhere when:

• Requirements include cross-language coverage (JS, Go, Python), frontend source-map symbolication, or mobile crash reporting.
• The org needs APM-grade capabilities: latency percentiles, dependency maps, alerting/on-call routing, release health, or SLO tracking.
• Historical backfill matters — frames are parsed client-side at write time, so existing records are unaffected; only new reports gain the corrected throw site and chained frames. If the goal is to fix past incident data, this release does not do that.
• Vendor-managed SLAs, SOC 2 attestations, or a support contract are procurement prerequisites.
• Nobody owns infrastructure operations; running a self-hosted error backend without an owner tends to decay into an unmonitored, full disk.
• The application relies on heavy async/queue or multi-service tracing where correlation IDs across services are the primary need.

Evaluation cautions specific to this release:

• The fix works by reusing an internal vendor parser for code-window extraction. That is a structural improvement over the previous greedy-regex string parsing (which broke on messages containing (1064): ), but it introduces a coupling to vendor internals worth testing on upgrade.
• Confirm the dashboard actually renders Caused by: labels after the corresponding server-side template change lands; without it the frames appear unlabelled, which can read as noise to reviewers.
• Validate that frame ordering and codeframe context lines match what the previous version produced for the caller frames, so existing triage habits still work.

How to Pitch It (Stakeholders)

To executives: Error reports were pointing engineers one frame away from where the bug actually was, and were discarding the underlying cause of wrapped exceptions — which is precisely the information needed to diagnose a failed query or a failed request. This release fixes both, at zero migration cost: no configuration changes, no downtime, no server-side protocol change, and no data leaves our infrastructure. The business outcome is shorter time-to-diagnosis on production incidents, fewer mis-assigned bugs, and continued avoidance of a per-seat SaaS error-tracking bill.

To engineering leadership: The change replaces fragile string parsing with a first-class path that reads the Throwable directly, so the first frame is the true throw site with the same surrounding code context as parsed frames. It additionally walks the getPrevious() chain and labels those frames Caused by:, recovering information the previous formatter dropped. collectFrames(string) remains as a fallback, and both the Laravel listener and the Monolog handler switch automatically when a Throwable is available. The wire format is unchanged (serialize(Codeframe[])), so rollout is a composer bump.

To the engineering team: Upgrading is a patch-level dependency bump with no code changes on our side. Two things to know: only newly captured reports benefit — old records keep their old frames, so do not expect historical incidents to improve; and to get the Caused by: labels rendered in the dashboard, the matching server-side template change (bug-catcher#19) must ship with or before our client upgrade. Recommend upgrading the client, staging the server template, and spot-checking a known nested-exception case (e.g. a QueryException-wrapped PDOException) before rolling across all services.

Ask: Approve the reporter upgrade as routine maintenance across PHP services, paired with the server-side template update, and treat "verify throw-site accuracy and chained-exception rendering on a known incident" as the acceptance criterion.