Weave Code
Backtrace Laravel Package
spatie/backtrace
Spatie Backtrace provides a cleaner, easier-to-use alternative to PHP’s debug_backtrace. It returns a structured list of Frame objects with accurate file, line, class/method info, and optional arguments, making traces simpler to inspect and filter.
A better backtrace
Frequently asked questions about Backtrace
- How does spatie/backtrace compare to Laravel’s built-in debug_backtrace() for error handling?
- Spatie/backtrace fixes key issues with `debug_backtrace()`, like skewed function names and bitmask options, by returning clean `Frame` objects with file, line, class, and method data. It integrates natively with Laravel’s `Throwable` and `base_path()` helpers, making it ideal for exception handlers or debugging tools where raw backtraces are unwieldy.
- Can I use this package in Laravel 8+ without breaking existing error handlers?
- Yes, the package is designed for Laravel 8+ and replaces `debug_backtrace()` incrementally. Start by testing it in a single exception handler or middleware to validate output before full adoption. It augments—not replaces—existing error handling, so no breaking changes are expected.
- Will enabling `withArguments()` in production slow down my Laravel app?
- No, argument collection is opt-in and only enabled when explicitly called (e.g., `Backtrace::create()->withArguments()`). For production, disable it or use `reduceArguments()` to minimize overhead. The package avoids global performance hits unless configured otherwise.
- How do I customize argument reduction for complex types like Carbon or Eloquent models?
- Implement the `ArgumentReducer` interface to handle custom types. For example, override `reduce()` to format Carbon instances as ISO strings or truncate Eloquent relationships. The package provides a fluent API (`withArguments()->reduceWith()`) to chain reducers for granular control.
- Does this package work with Laravel’s debugbar or Monolog for logging backtraces?
- Absolutely. Spatie/backtrace integrates seamlessly with Laravel’s debugging tools. Use `Backtrace::create()->getFramesAsArray()` to feed data into debugbar or format it for Monolog. The `trimFilePaths()` method also standardizes paths for cleaner logs.
- What PHP version and Laravel compatibility does spatie/backtrace support?
- The package supports PHP 7.3–8.4 and Laravel 8+. For older Laravel versions (e.g., 7.x), test `base_path()` compatibility manually, as some helper methods assume newer Laravel conventions. Always check the [release notes](https://github.com/spatie/backtrace/releases) for updates.
- How do I mock `Backtrace::create()` in PHPUnit tests?
- Use PHPUnit’s partial mocking to replace `Backtrace::create()` with a test double. For example, create a mock `Backtrace` instance with predefined `Frame` objects using `Frame::fromArray()`. This is useful for validating exception handling logic without relying on real backtraces.
- Will this package conflict with other debug tools like Whoops or Laravel Telescope?
- No conflicts are expected, but validate if other packages modify `debug_backtrace()`. Whoops and Telescope typically wrap or extend backtraces, so spatie/backtrace can coexist. Test in a staging environment to ensure compatibility with your stack.
- How do I handle `open_basedir` restrictions when using `getSnippetAsString()`?
- If `open_basedir` blocks file access, catch `RuntimeException` and fall back to line numbers or method names. The package doesn’t enforce snippet retrieval—it’s optional. For restricted environments, disable snippets or use `trimFilePaths()` to focus on essential data.
- Is there a performance difference between `Backtrace::create()` and `debug_backtrace()`?
- The package abstracts `debug_backtrace()` but adds minimal overhead for parsing frames. The biggest performance impact comes from `withArguments()` or `withObject()`, which require reflection. Benchmark in your environment, but expect negligible differences unless using argument collection globally.
Weaver
How can I help you explore Laravel packages today?