Backtrace Laravel Package

Product Decisions This Supports

• Debugging & Observability:

  • Enhance error tracking and logging systems (e.g., Sentry, Laravel Debugbar) with richer, more readable stack traces.
  • Build a custom error reporting dashboard with granular frame-level insights (e.g., arguments, objects, code snippets).
  • Improve developer onboarding by surfacing cleaner, contextual backtraces in IDEs or internal docs.

• Performance & Cost Optimization:

  • Replace custom backtrace parsing (e.g., regex-based solutions) with a maintained, battle-tested library.
  • Reduce debugging time for critical paths (e.g., payment failures, API timeouts) by filtering vendor frames and focusing on application logic.

• Security & Compliance:

  • Audit logging with structured backtraces to trace unauthorized access or data leaks to specific code paths.
  • PII redaction by extending ArgumentReducer to mask sensitive data (e.g., passwords, tokens) in stack traces.

• Roadmap Alignment:

  • Leverage for Laravel-specific tools: Integrate with Laravel’s artisan or Statamic’s please CLI commands to exclude them from application frames (already supported).
  • Extend for microservices: Use applicationPath to distinguish between service-specific backtraces in distributed systems.

• Build vs. Buy:

  • Buy: Avoid reinventing wheel for backtrace parsing (e.g., no need to maintain regex or manual frame filtering).
  • Customize: Extend via ArgumentReducer or Frame properties for niche use cases (e.g., custom argument formatting for domain objects).

When to Consider This Package

• Adopt if:

  • Your team spends >20% of debugging time parsing raw debug_backtrace() output.
  • You need vendor/application frame separation (e.g., for Laravel/Statamic projects).
  • You require argument/object inspection in stack traces (e.g., for debugging complex logic).
  • Your error logs are noisy with irrelevant vendor frames (e.g., Symfony, Guzzle).
  • You’re building internal tools (e.g., error dashboards, IDE plugins) that need structured backtrace data.

• Look elsewhere if:

  • You’re using non-PHP languages (e.g., Python, JavaScript).
  • Your stack traces are already sufficient (e.g., minimal vendor noise, no need for arguments/objects).
  • You require real-time backtrace analysis (e.g., APM tools like New Relic; consider native extensions instead).
  • Your project is PHP <7.3 (package drops support for older versions).
  • You need low-level performance (e.g., high-frequency backtraces in kernels; this adds slight overhead).

How to Pitch It (Stakeholders)

For Executives:

"This package transforms how we debug PHP applications by replacing cryptic debug_backtrace() output with structured, actionable stack traces. For example:

• Save 30%+ debugging time by filtering out vendor noise (e.g., Laravel/Statamic CLI commands) and surfacing only application code.
• Reduce MTTR for critical issues by including arguments/objects in errors (e.g., see exactly what data caused a failure).
• Future-proof observability with extensible features like custom argument reducers (e.g., masking PII in logs). It’s a low-risk, high-reward investment—like upgrading from a manual screwdriver to a power tool for debugging."

For Engineering Teams:

"Spatie’s backtrace solves three key pain points:

1. Cleaner Output: Fixes debug_backtrace()’s quirks (e.g., skewed function names) and adds properties like applicationFrame to distinguish your code from vendor libraries.
2. Rich Data: Fetch arguments/objects without sacrificing performance (opt-in via withArguments()). Reduce clutter with custom ArgumentReducer classes (e.g., format DateTime objects).
3. Laravel/Statamic Support: Automatically excludes artisan/please from application frames—no manual config needed. Use cases:

• Error tracking: Plug into Sentry/Laravel Debugbar for richer context.
• Logging: Attach structured backtraces to audit trails.
• Dev tools: Build IDE plugins or internal dashboards with frame-level insights. It’s MIT-licensed, actively maintained, and used by 435+ repos. Let’s prototype it for our top 3 debugging bottlenecks."

For Developers:

"Swap debug_backtrace() for this in 5 minutes:

$frames = Spatie\Backtrace\Backtrace::create()
    ->withArguments()
    ->applicationPath(base_path())
    ->trimFilePaths()
    ->frames();

// Now you get:
// - `frame->file` (relative to app root)
// - `frame->arguments` (with custom reducers)
// - `frame->applicationFrame` (bool: is this our code?)

Pro tip: Use startingFromFrame() to isolate stack traces to specific classes/methods. Perfect for unit tests or CLI debugging."*