Weave Code
Backtrace Laravel Package
spatie/backtrace
A cleaner, more useful PHP backtrace than debug_backtrace(). Create a Backtrace, get frames as typed Frame objects with correct file, line, class/method, and optional arguments, making stack traces easier to inspect, filter, and work with.
A better backtrace
Frequently asked questions about Backtrace
- How do I replace debug_backtrace() in Laravel with Spatie\Backtrace?
- Replace `debug_backtrace()` with `Spatie\Backtrace\Backtrace::create()->frames()`. For example, swap `$trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 5);` with `$trace = Spatie\Backtrace\Backtrace::create()->limit(5)->frames()`. The package handles Laravel’s vendor frames (like Artisan) automatically.
- Will this work with Laravel’s exception handling (App\Exceptions\Handler)?
- Yes. Use `Backtrace::createForThrowable($exception)` in your `render()` method to attach structured traces to exceptions. It integrates seamlessly with Laravel’s built-in error handling without modifying core files.
- Does Spatie\Backtrace support PHP 8.1+ features like named arguments?
- Yes, the package fully supports PHP 8.1+. Named arguments are captured and displayed clearly in the `Frame` objects. For older PHP versions (7.3+), it falls back to standard argument handling.
- How do I exclude vendor frames (e.g., custom CLI commands) from the backtrace?
- Use `Backtrace::create()->ignoreVendorFrames(false)` to manually exclude vendor frames. For custom CLI files (e.g., `artisan` or Statamic), the package already filters them by default. If needed, extend the `VendorFrameDetector` class.
- Is there a performance impact when capturing arguments/objects in production?
- Yes, capturing arguments (`withArguments()`) or objects (`withObject()`) adds CPU/memory overhead. Avoid this in production unless debugging critical paths. Use it selectively in development/staging with `Backtrace::create()->withArguments()->limit(10)`.
- Can I customize how arguments are displayed (e.g., mask sensitive data)?
- Absolutely. Register a custom `ArgumentReducer` via `Backtrace::create()->argumentReducer(fn($arg) => maskSensitiveData($arg))`. This is useful for masking passwords, API keys, or PII in logs or error reports.
- Does this package work with Laravel Debugbar or Sentry?
- Yes. For Debugbar, replace `debug_backtrace()` in collectors with `Backtrace::frames()`. For Sentry, use `Backtrace::createForThrowable($exception)` to attach enhanced traces to errors. Both tools recognize the structured `Frame` objects.
- How do I test backtrace accuracy in Laravel unit tests?
- Mock `Spatie\Backtrace\Backtrace::create()` in tests to return predefined `Frame` objects. For example, use `Backtrace::shouldReceive('create')->andReturn($mockBacktrace)` in PHPUnit. Verify critical paths (e.g., payment failures) log correct stack traces.
- Are there alternatives to Spatie\Backtrace for Laravel debugging?
- Native `debug_backtrace()` is the closest alternative, but lacks structured `Frame` objects and Laravel-specific optimizations. For advanced use cases, consider `xdebug` (for dev) or `Whoops` (for pretty errors), but neither offers the same integration with Laravel’s ecosystem.
- How do I handle open_basedir restrictions when capturing file paths?
- The package includes a fix for `open_basedir` restrictions (since v1.7.4). If you encounter issues, ensure your server’s `open_basedir` includes the project root. Test locally with `Backtrace::create()->getFrames()` to confirm paths resolve correctly.
Weaver
How can I help you explore Laravel packages today?