Friendly Exception Laravel Package

Product Decisions This Supports

• Developer Experience (DX) Initiatives:

  • Prioritize debugging efficiency by reducing time spent parsing raw stack traces (aligns with "reduce toil" goals).
  • Enable self-service debugging for mid-level engineers, reducing reliance on senior devs for error resolution.
  • Support consistent error formatting across microservices or monoliths (critical for distributed teams).

• Roadmap Priorities:

  • Observability Stack: Integrate with existing tools (e.g., Sentry, Datadog) for unified error tracking while improving local debugging.
  • Security Hardening: Replace ad-hoc error pages with production-safe outputs (compliance with GDPR/PCI for sensitive apps).
  • Framework Agnosticism: Standardize error handling across PHP-based services (e.g., legacy Yii apps + new Laravel services).

• Build vs. Buy:

  • Buy: Avoid reinventing error-page UX (e.g., custom Twig templates, stack-trace parsers). Low maintenance cost for high ROI.
  • Extend: Use as a base for custom error handlers (e.g., adding Jira ticket links, Slack alerts).
  • Replace: Sunset legacy Whoops or Symfony Debug if they lack modern features (e.g., source context, prod safety).

• Use Cases:

  • Internal Tools: Accelerate debugging for devs using CLI/web interfaces.
  • Customer-Facing Apps: Serve 500 pages with minimal PII exposure (e.g., ?debug=1 for support teams).
  • APIs: Log structured errors to ELK/Splunk while showing devs rich context locally.

When to Consider This Package

Adopt If:

• Your team spends >20% of dev time parsing stack traces or guessing error causes.
• You need consistent error pages across PHP services (e.g., migrating from Yii to Laravel).
• Production errors currently expose sensitive data (e.g., file paths, query strings).
• You’re using Yii, Lumen, or framework-agnostic PHP and want a lightweight solution.
• Your CI/CD pipeline lacks robust error logging (e.g., no Sentry integration yet).

Look Elsewhere If:

• You’re all-in on Symfony: Use symfony/debug or symfony/error-handler instead.
• You need real-time error monitoring: Pair with Sentry, Rollbar, or Bugsnag (this package focuses on local/dev rendering).
• Your stack is non-PHP (e.g., Node.js, Go, Python).
• You require enterprise-grade APM: Tools like New Relic or Dynatrace offer deeper insights.
• Your team prefers minimalist error pages: This adds visual overhead (though highly customizable).

Avoid If:

• You’re already satisfied with your current error-handling solution (e.g., Whoops + custom templates).
• Your app never hits production errors (unlikely, but possible for trivial scripts).

How to Pitch It (Stakeholders)

For Executives (TL;DR):

"This package turns cryptic PHP errors into clear, actionable debug pages—saving devs hours weekly. For $0 cost, we get:

• Faster bug fixes: Stack traces with source code context (no more guessing).
• Safer production: Automatically hides sensitive data in live errors.
• Consistency: Works across all PHP services, reducing training overhead. It’s like Google Maps for debugging—instead of a raw GPS coordinate (stack trace), devs see a street view (exact line + context)."

Ask: "Should we prioritize this for the next sprint to cut debugging time by 30%?"

For Engineering (Technical Value):

"yiisoft/friendly-exception solves three key pain points:

1. Dev Experience:

   • Replaces ugly Uncaught Exception dumps with structured, collapsible error pages.
   • Shows file context (e.g., 3 lines above/below the error) to pinpoint issues instantly.
   • Works in CLI and web (critical for debugging cron jobs).

2. Production Safety:

   • Automatically sanitizes output (e.g., hides APP_KEY, DB credentials).
   • Supports environment-based rendering (dev vs. prod templates).

3. Flexibility:

   • Framework-agnostic: Drop into Yii, Laravel, or raw PHP.
   • Extensible: Override renderers to add custom metadata (e.g., user session data for context).
   • Lightweight: ~500 LOC core, no bloat.

Integration Effort: 1–2 hours for basic setup (middleware + config). Example:

// In Laravel: Replace App\Exceptions\Handler
use Yiisoft\FriendlyException\Renderer\Renderer;

public function render($request, Throwable $exception) {
    return (new Renderer())->render($exception);
}

Trade-offs:

• Slightly larger error pages than minimalist tools (but highly configurable).
• Focuses on local debugging; pair with Sentry for production monitoring.

Recommendation: Pilot in one service (e.g., a high-error-rate API) to measure dev time savings."*