Weave Code
Backtrace Laravel Package
spatie/backtrace
Spatie's PHP package offers a cleaner alternative to debug_backtrace for working with backtraces. Create a Backtrace instance, get an array of Frame objects, and easily read each frame's file, line number, class, method, arguments, and object.
A better backtrace
Frequently asked questions about Backtrace
- What is spatie/backtrace and why use it instead of debug_backtrace()?
- spatie/backtrace is a small, framework-agnostic PHP utility that wraps debug_backtrace() and returns an array of typed Spatie\Backtrace\Frame objects instead of raw arrays. Each frame exposes file, lineNumber, class, method, arguments, and object properties, so you avoid the shifted function-name semantics and the DEBUG_BACKTRACE_IGNORE_ARGS bitmask juggling. It also adds application-versus-vendor frame classification and argument reduction, which is where it earns its place over a hand-rolled helper.
- How do I install spatie/backtrace in a Laravel application?
- Run composer require spatie/backtrace. There is no service provider, facade, config file, or publish step, so nothing needs to be registered in bootstrap/providers.php or config/app.php. You can call Backtrace::create()->frames() immediately inside an exception handler, middleware, or Artisan command.
- Which Laravel and PHP versions does spatie/backtrace support?
- The package is framework-agnostic and has no Laravel coupling, so it works with any Laravel version whose PHP constraint it satisfies; check the composer.json on Packagist for the current PHP minimum. Laravel-specific behavior is limited to conventions such as passing base_path() as the application path and the special-casing of artisan and please as vendor frames. There is nothing to configure per Laravel release.
- How do I capture frame arguments and objects with spatie/backtrace?
- Call withArguments() before frames() to populate the arguments property, and withObject() to include the object for each frame. Without those calls, Frame::$arguments is null. Objects and full argument payloads are held live, so reserve this for debugging and diagnostics rather than high-traffic production paths.
- How do I stop sensitive data leaking into logs with spatie/backtrace?
- Use reduceArguments() together with a custom ArgumentReducer implementation to normalize arguments into safe, loggable strings and to redact or drop sensitive types. Treat this as mandatory before the package touches production logging or error pages, because withArguments() and withObject() otherwise retain full payloads and live object graphs. Review anything your exception renderer or structured log context serializes as well.
- Why are arguments missing when I use createForThrowable()?
- PHP only records throwable arguments when the zend.exception_ignore_args INI setting is 0 at the moment the throwable is created, and objects are never included. That setting commonly differs between local development, FPM, and CLI, so alerting or rendering logic that assumes arguments exist will degrade silently. Check the INI value per environment instead of assuming arguments are present.
- How do I get only application frames and skip vendor frames?
- Pass your project root, typically base_path(), to applicationPath(), then use the applicationFrame property or firstApplicationFrameIndex to find the first non-vendor frame, or filter on the per-frame applicationFrame flag. You can narrow the output further with offset(), limit(), and startingFromFrame() on the builder. Note that artisan and Statamic's please are classified as vendor frames, and that 1.8.0 and 1.8.1 changed classification semantics, so pin the version if downstream logic depends on it.
- Is spatie/backtrace safe to use inside a production error handler?
- Building the trace itself is cheap, but snippet generation reads source files, is subject to open_basedir, and has already produced a crash-class bug where the file path was a directory. Error handlers run when the system is already failing, so wrap snippet rendering in a try/catch or disable it in production. Pin to a known minor version as well, since 1.7.2, 1.8.0, and 1.8.1 all changed observable behavior.
- How do I test code that uses spatie/backtrace?
- Backtrace::create() returns plain Frame value objects and the package has no global state, service provider, or container bindings, so you can unit test your handler by asserting on file, lineNumber, class, and method values from a known call site. If your logic depends on vendor classification, pass an explicit applicationPath() in tests so results stay deterministic across CI environments.
- Is spatie/backtrace actively maintained, and what are the alternatives?
- It is a single-vendor Spatie package with an active release cadence, a changelog, Dependabot, a security policy, and an MIT license, but no SLA, so version pinning is sensible rather than paranoid. Alternatives include parsing debug_backtrace() yourself, Symfony's error handler, or the trace facilities bundled with Laravel and Ignition. Most teams choose spatie/backtrace when they want typed frames plus argument reduction without adopting a full error-handling stack.
Weaver
How can I help you explore Laravel packages today?