Bug Catcher Reporter Bundle Laravel Package

Getting Started

• Install with Composer (composer require php-bug-catcher/reporter-bundle); Laravel auto-discovers the service provider. Publish the package config if you need to override defaults, then set the project key/endpoint in .env.
• First place to look is the package config file, specifically stack_trace. It already defaults to true in v2.1.1 — leave it on. Turning it off is the fastest way to lose the value this release adds.
• The core entry point is BugCatcher::logException($throwable). Call it from a catch block, a report() override, or your global exception handler's report path.
• First use case: ship it, let an uncaught exception happen in a non-production environment, and open the report. Confirm the first code frame points at the throw / call site in your code — not at the caller one level up. That is the headline fix in v2.1.1.
• If you want zero-touch capture, wire the Monolog handler instead of calling the facade manually. It picks up context['exception'] automatically.

Implementation Patterns

• Explicit logging in domain code. Wrap risky operations and call BugCatcher::logException($e) in the catch. This gives you control over which exceptions are worth a report and lets you attach context before it ships.
• Automatic capture via Monolog. Register BugCatcherMonologHandler on the exception-handling channel. In v2.1.1 it detects a Throwable in context['exception'] and uses ThrowSiteStacktrace directly; anything else falls back to the old formatted-string parser. You get the fixed frame ordering without touching call sites.
• Trust the Caused by: chain. The new ThrowSiteStacktrace walks getPrevious() and labels those frames. If you routinely wrap low-level exceptions (QueryException inside a domain exception, etc.) this is now the fastest way to see the original failure without leaving the report.
• Extension point for custom transports. CollectCodeFrame::collectThrowableFrames(Throwable) is public and is now the preferred API if you build your own reporting path or push frames into a different sink. collectFrames(string) still exists as the string fallback — keep it only for legacy inputs.
• No wire-format work needed. Payloads are still serialize(Codeframe[]). If you have an in-house consumer, ingestion pipe, or test fixture asserting on the serialized shape, nothing changes.
• Upgrade path is a no-op. No config keys, no constructor signature changes, no new services. Bump the constraint, run the test suite, deploy.

Gotchas and Tips

• Existing reports stay wrong. Frames are parsed at write time on the client, so historical reports keep the old off-by-one first frame and the missing Caused by: chain. Nothing backfills. Don't debug old reports assuming they reflect the new parser.
• The old first frame was genuinely the caller. If you have runbooks or alert rules that keyed off "first frame = throw site," they were already compensating for the bug. Re-check any logic that skipped #0.
• Caused by: labels need a server-side update. You need the matching php-bug-catcher/bug-catcher#19 template change deployed. Without it the previous-chain frames still appear in the dashboard — they just aren't labelled, which is confusing rather than broken. Deploy both sides together where possible.
• The old greedy regex was a real corruption source. The pre-2.1.1 Monolog path prepended a synthetic #0 file(line): message line and re-parsed it with /#\d+ (.*)\((\d+)\): (.*)/. Any exception message containing a (digits): pattern (MySQL error codes, for example) hijacked the file and line. If you see pre-upgrade reports with a :0 line number, that's this bug — not your code.
• Remove local workarounds. If you prepended your own synthetic frame, wrote a custom formatter to fix the off-by-one, or manually reordered frames after collection, delete that now. It will double-count or fight the new path.
• Monolog fallback is still live. Passing a pre-formatted trace string in context['exception'] (rather than a Throwable) keeps you on the old parsing path. If a custom handler stringifies exceptions before this handler sees them, you silently lose the fix.
• stack_trace must be true. It defaults to true in this release, but if an earlier config publish or an environment override set it to false, the new throw-site path never runs and you'll see no frames at all.
• Watch frame volume. Previous-chain walking can substantially increase report payloads for deeply wrapped exceptions. If you have payload-size limits or sampling on your ingestion side, sanity-check a worst-case wrapped exception after upgrading.