Reporter Bundle Laravel Package

Getting Started

• Install with composer require php-bug-catcher/reporter-bundle. v2.1.1 is a drop-in patch over v2.1.0 — no new config keys, services, or constructor signatures.
• Publish the package config if you need to override defaults (php artisan vendor:publish --tag=bug-catcher-config); the only relevant key here is stack_trace, which already defaults to true.
• Configure your Bug Catcher endpoint/credentials in .env as documented by the package.
• Decide on your capture path:
  • Monolog: add BugCatcherMonologHandler to the channel(s) that receive exceptions (config/logging.php), so anything logged with ['exception' => $throwable] is reported with a codeframe.
  • Direct: call BugCatcher::logException($throwable, $context) from your exception handler or a catch block.
• First use case: throw a test exception, capture it, and confirm the first frame in the Bug Catcher UI is now the actual throw site (file/line where the exception was constructed or thrown), not its caller.

Implementation Patterns

• Global reporting via Laravel's exception handler. Hook BugCatcher::logException($e) into bootstrap/app.php (->withExceptions(...)->report(...)) or your App\Exceptions\Handler. This is the simplest catch-all for HTTP and console exceptions.
• Monolog channel integration. Add the handler to a channel's tap array. Because BugCatcherMonologHandler inspects context['exception'], prefer Log::error($e->getMessage(), ['exception' => $e]) over string interpolation — that is what enables the throw-site codeframe and the getPrevious() chain.
• Wrap-and-rethrow for domain context. throw new DomainException('Order failed', 0, $e); now produces a chain: the outer exception gets the throw-site frame, and previous exceptions are appended and labelled Caused by: .... This is the intended way to preserve root cause.
• Queue/job failures. Report from failed(Throwable $e) or let the global handler do it. Always pass the Throwable object, not a formatted trace string.
• Custom frame collection. CollectCodeFrame::collectThrowableFrames($throwable) gives you the throw-site-first frames (with the vendor parser's code-window context). collectFrames(string) remains as a fallback for already-formatted traces.
• Custom transports / storage. The wire format is still serialize(Codeframe[]), so existing serializers, queues, and server endpoints need no changes. WriteStackTraceListener always uses the new throw-site path; the Monolog handler uses it whenever context['exception'] is a Throwable and falls back to the formatted string otherwise.
• Dashboard labels. To render the Caused by: labels you need the matching server-side template change (php-bug-catcher/bug-catcher#19). The extra frames still appear without it; only the label is missing.

Gotchas and Tips

• getTraceAsString() never contains the throw site. Its #0 is already the caller. If you have custom code that parses that string expecting #0 to be the origin, it is off by one. Use getFile() / getLine() or ThrowSiteStacktrace instead.
• The old error formatter regex is greedy. ErrorFormater previously prepended a synthetic #0 file(line): message and parsed it back with /#\d+ (.*)\((\d+)\): (.*)/. A message containing something like (1064): could swallow the real file and line. If you maintain a fork or custom parser, make the file/line groups non-greedy or parse the Throwable directly.
• context['exception'] must be an actual Throwable. If you log a string, array, or already-rendered trace, the Monolog handler falls back to collectFrames(string) and you lose both the throw site and the previous-exception chain.
• Existing records are not backfilled. Frames are parsed client-side at write time; only new reports after upgrading get throw-site and Caused by: frames.
• Source files must exist on the reporting host. The new path reuses the vendor parser's code-window extraction, so stripped production deploys (no source, only opcache/prebuilt artifacts) will still lack context lines.
• Previous chains increase payload size. Deep wrap-and-rethrow chains now serialize more Codeframe objects. There is no new depth-limit config in this release; trim wrapping at the source if payload size matters.
• Debugging a missing throw site: confirm you are on v2.1.1, confirm the report went through WriteStackTraceListener or the Monolog handler with a real Throwable, and confirm stack_trace is true.
• Upgrade is safe. No config migration, no new bindings, no signature changes — a plain composer update is sufficient.