Backtrace Laravel Package

Product Decisions This Supports

• Build vs. buy for error diagnostics. This package answers the question "do we write our own backtrace parser?" with a no. It replaces debug_backtrace()'s awkward bitmask options and off-by-one frame attribution with an explicit builder API (Backtrace::create()->frames()), typed Frame objects, and named properties (file, lineNumber, class, method, arguments, object, applicationFrame). Adopting it converts a multi-week internal utility into a composer require.
• Roadmap for the error-reporting / support-experience surface. If your backlog contains items like "make exception pages more useful," "attach cleaner context to bug reports," or "let support see where a failure originated in our code, not vendor code," this package is the enabling primitive. The applicationPath(base_path()) and applicationFrame flag mean you can ship a feature that highlights the first application-owned frame — the one a developer actually needs — instead of a wall of Composer internals.
• Prioritizing privacy and PII work in logs and exception payloads. withArguments() is opt-in for performance and safety reasons, and reduceArguments() with pluggable ArgumentReducer implementations lets you define exactly how objects (e.g., DateTimeInterface) get stringified before leaving the process. This is a concrete lever for GDPR/compliance-driven roadmap items: you can ship diagnostic context without shipping raw request objects into a log aggregator.
• Deciding how much of the tracing problem is in scope. This package is a formatting and filtering layer over PHP's native stack, not an APM. That distinction is a roadmap decision: it justifies deferring investment in distributed tracing/OpenTelemetry while still delivering a materially better in-process diagnose experience.
• Support-triage and internal tooling feature bets. limit(), offset(), startingFromFrame(), trimFilePaths(), and code-snippet access (getSnippetAsString) are directly usable for a "copy this trace into a ticket" button, a CLI --debug flag, or a sanitized trace block in an error email — small, shippable features with visible support-cost reduction.
• Use-case fit: custom exception handlers/renderers, Laravel log context enrichment, first-party error pages, developer-facing CLI diagnostics, and internal QA tooling. It is not a fit for production request tracing at scale.

When to Consider This Package

Consider adopting when:

• You are writing or maintaining a custom exception handler, error renderer, or diagnostics endpoint in a Laravel (or plain PHP) app and currently hand-rolling backtrace parsing.
• You need the application-vs-vendor distinction — filtering out framework/Composer noise is the single highest-value capability here, and the package already handles edge cases you would not think of (Laravel's artisan and Statamic's please CLI entrypoints are treated as vendor files; the top frame is correctly classified).
• You need controlled argument serialization for privacy reasons and want per-type reducers rather than an all-or-nothing json_encode.
• You want exception backtraces with a consistent API (Backtrace::createForThrowable($e)), accepting the documented caveat that arguments depend on zend.exception_ignore_args=0 being set before the throw and that objects are never available on that path.
• You want a small, MIT-licensed, low-surface-area dependency with a real changelog and a steady release cadence (1.8.2 is the current line; PHP 8.4 support landed in 1.7.0).

Look elsewhere when:

• You need APM, distributed tracing, or span collection. Use OpenTelemetry, or lean on Sentry/Bugsnag/Flare — these already solve tracing end-to-end, and this package would be redundant plumbing beneath them.
• Laravel Telescope, Ignition/Flare, or Whoops already cover your need. Note that this library is realistically consumed transitively by those tools; check composer why spatie/backtrace before adding a direct dependency, or you may be formalizing something you already ship.
• You need a vendor with an SLA or commercial support. This is a Spatie open-source utility with a small maintainer base — typical of the ecosystem, but a real consideration if trace fidelity is on a critical path.
• Supply-chain diligence flags it. The reported dependent count is 0 and stars are modest (438). Treat that as a signal to check actual transitive usage in your lockfile rather than an indictment — but if your policy gates on adoption breadth, this may not clear the bar on paper.
• You need long-term trace retention or storage. The package gives you frames; it does not persist, aggregate, or alert. Pairing it with a real error backend is a prerequisite, not a follow-on.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a recurring class of cost — engineers and support spend time reconstructing where a failure happened from raw PHP stack traces that are noisy, misleading, and often expose internal objects. spatie/backtrace is a small, MIT-licensed, actively maintained utility that turns those traces into clean, structured, privacy-safe data with one line of configuration. It is a low-risk enabler for error-page quality, support-triage speed, and PII-safe logging, and it costs us a Composer dependency rather than a build cycle. It is not a monitoring product — it is the formatting layer that makes our existing error handling and error backends actually usable.

For engineering (the pitch): Stop writing backtrace parsers. Backtrace::create()->applicationPath(base_path())->frames() gives you Frame objects with correct class/method attribution (PHP's native version skews the function name to the previous frame), an applicationFrame boolean that already knows about artisan/please edge cases, opt-in withArguments()/withObject() for performance, and a reducer system for safely stringifying objects before they hit a log. Use limit/offset/startingFromFrame to carve out the slice you care about, trimFilePaths to keep paths relative in output, and createForThrowable when you're starting from an exception. It is a thin, well-tested wrapper — no framework lock-in, no runtime service, PHP 8.4 ready.

Risks to state up front: thin abstraction over a native PHP primitive (so the value is ergonomics plus edge-case handling, not novel capability); small maintainer surface; likely already present transitively via Ignition/Flare, so confirm before adding it directly. Mitigation: it is MIT, dependency-light, and trivially replaceable — the cost of being wrong is a one-file swap.