Reporter Bundle Laravel Package

Technical Evaluation

Architecture fit

• reporter-bundle is a client-side Laravel/PHP reporter: it hooks Laravel's exception handling (WriteStackTraceListener) and Monolog (BugCatcherMonologHandler) and ships serialize(Codeframe[]) payloads to a separate Bug Catcher server. Treat it as two products with one contract — the client package and the server (php-bug-catcher/bug-catcher) — and plan versioning accordingly.
• Functionally adjacent to Sentry/Flare/Bugsnag in the observability slot. Evaluation criteria should be the same: capture fidelity, payload cost, failure isolation, and self-hosting burden. This is a self-hosted stack, so "who operates the server" is a real staffing question, not a footnote.
• The PHP-native serialize() wire format is the main architectural smell for a TPM to flag: it works only because both ends are PHP, and it forecloses non-PHP consumers, log-pipeline inspection, and easy payload diffing in transit. Not a blocker for a PHP-only estate; a blocker if you ever want to route reports through anything else.

Integration feasibility

• Very high. Explicitly drop-in: no config keys, no new services, no constructor signature changes, stack_trace already defaulted to true. Upgrade is a composer update and a deploy.
• The one external dependency is a server-side template change (#19) for the Caused by: labels. The release degrades gracefully without it — extra frames appear, label absent — so the client upgrade need not be gated on the server team. That is good release engineering and low coordination cost.

Technical risk

• The bug being fixed is a data-quality defect in the primary diagnostic artifact. The first frame was the caller, one frame off from the throw site, and the Monolog path additionally mis-parsed file/line whenever an exception message contained a (NNNN): sequence (e.g. SQLSTATE codes) because of a greedy regex. Engineers reading these traces were being pointed at the wrong line with no visible signal that anything was wrong. Silent wrongness in an error tool is worse than a visible failure.
• The greedy-regex class of defect is worth auditing elsewhere; it is a pattern that recurs in log parsing.
• Walking getPrevious() is a genuine capability addition, not just a fix — chained/causal exceptions are now visible, which directly improves root-cause time on layered failures (DB → repository → service). It also increases payload size and the volume of exception message text leaving the process, which has PII and quota implications.
• The new path extracts a code window from disk at throw time. If the source file is not readable in the runtime environment (opcache-only or stripped deploys, container images without source, files deleted post-deploy), the frame builder must fail soft. A throw inside the exception handler would mask the original error — the single worst failure mode for a reporter. Verify this explicitly; it is not addressed in the notes.

Key questions

• Is the package version pinned in composer.json, and what is the fleet rollout mechanism?
• Can ThrowSiteStacktrace throw when source is unreadable, and is it wrapped defensively?
• What is the payload size delta for a 5-deep exception chain, and does it approach any request/body limits on the collector?
• Does the collector authenticate and encrypt the ingest endpoint (relevant given unserialize on the receiving end)?
• Is there message scrubbing/retention policy covering the newly captured previous chain?
• When is server-side #19 shipping, and does the dashboard silently tolerate unlabeled frames?

Integration Approach

Stack fit

• Standard Laravel service-provider package; no new infrastructure, no queue, no daemon. Fits an existing Laravel estate without platform work.
• Works alongside or as a replacement for a commercial reporter. If replacing, do a parallel-run window before decommissioning the incumbent — capture fidelity is the thing you are buying, and this release is precisely a fidelity fix.

Migration path

• composer update to 2.1.1 and deploy. No config migration, no data migration, no service registration changes.
• No backfill is possible or needed: frames are parsed client-side at write time, so historical records retain the old off-by-one first frame permanently.

Compatibility

• Wire format unchanged (serialize(Codeframe[])), so old servers accept new clients.
• Server template #19 is a soft dependency: absent it, frames render without Caused by: labels. Degradation is cosmetic, which is the right design.
• Confirm the package's PHP and Laravel version constraints against the estate before assuming a clean bump — the notes don't restate them.

Sequencing

1. Land the client bump in one low-traffic environment; force a multi-level chained exception and confirm the first frame is the throw site and Caused by: frames appear.
2. Verify the source-unreadable case (simulate a stripped deploy) — confirms fail-soft behavior before fleet rollout.
3. Roll the client out across the fleet.
4. Ship server template #19; labels activate with no further client work.
5. Annotate the deploy date on trace-related dashboards (see below).

Operational Impact

Maintenance

• Small footprint: two capture paths, both now routed through the same frame builder, which reduces drift between the exception-handler and Monolog paths. That convergence is the durable maintenance win in this release, more than the specific bug.
• Ongoing cost is the self-hosted server, its storage growth, and keeping the client/server pair in step for render features.

Support

• Expect a short-lived uptick in "the trace looks different" questions from engineers; the first frame now legitimately differs. Brief the on-call rotation, don't just ship.
• Server team must own #19; without it the feature is half-delivered and will generate "why are there unlabeled frames" tickets.

Scaling

• Payload per exception grows with chain depth and with per-frame code windows. For high-volume error paths (a hot 500 loop), this is a real egress and storage multiplier — measure on one representative service before fleet-wide rollout.
• Ingest is in the exception path, so reporter latency is user-facing latency during incidents. Confirm timeouts and that reporting is non-blocking or bounded.

Failure modes

• Source file unreadable at throw time → code-window extraction fails inside the handler → masks the original exception. Highest-severity risk; test explicitly.
• Server template not deployed → extra frames render unlabeled. Cosmetic, acceptable.
• Mixed client versions across services → inconsistent trace quality in a single dashboard; confusing during cross-service incident triage.
• Deeply chained or recursive exceptions → oversized payloads, dropped reports precisely when you need them most.
• Unscrubbed previous chain → sensitive strings from nested exceptions leaving the process.

Ramp-up

• Low for engineers: no new config, no new concepts. The one behavioral instruction that matters is do not compare traces across the upgrade boundary — pre-2.1.1 first frames are wrong, so any metric or heuristic keyed on "top frame file/line" (auto-assignment rules, clustering, MTTD baselines) will shift discontinuously at deploy. Annotate dashboards with the rollout date before shipping, not after.