Simple Exception Laravel Package

Product Decisions This Supports

• Standardized Error Responses for APIs: Implement consistent JSON error formats across all API endpoints (e.g., { "error": "public_message", "debug": null }), improving client SDKs and documentation. This aligns with roadmap items for API-first development and developer experience (DX).

• Debugging Efficiency: Accelerate incident response by centralizing technical error details in logs while shielding users from sensitive data. Supports SRE/DevOps goals for faster MTTR (Mean Time to Resolution).

• Build vs. Buy for Core Utilities: Avoid reinventing exception handling for a low-risk, high-reward feature. The package’s simplicity reduces technical debt compared to custom solutions or framework-specific alternatives (e.g., Symfony’s ErrorHandler).

• Use Cases:

  • SaaS Platforms: Standardize error handling across tenant-specific APIs.
  • E-Commerce: Provide clear user messages (e.g., "Payment failed") while logging technical details (e.g., "Stripe API timeout").
  • Legacy System Modernization: Retrofit inconsistent exceptions in monolithic apps without full rewrites.
  • Microservices: Enforce uniform error formats across services (though lightweight alternatives like Laravel’s native exceptions may suffice).

• Roadmap Alignment:

  • Phase 1: Pilot in high-visibility modules (e.g., checkout, auth) to demonstrate ROI.
  • Phase 2: Expand to all custom exceptions as part of a quality initiative.
  • Phase 3: Integrate with observability tools (e.g., Sentry, Datadog) for advanced error tracking.

When to Consider This Package

• Adopt if:

  • Your primary language is PHP/Laravel, and you need structured exception handling without framework bloat.
  • You’re building APIs or services where error responses must follow a consistent schema (e.g., public/debug separation).
  • Your team prioritizes maintainability over cutting-edge features (e.g., no need for nested exceptions or localization).
  • You’re using PHP 7.4+ and can tolerate low-maintenance open-source (last update 2021).
  • You want to reduce boilerplate in exception classes (e.g., no more repeating public/private message logic).

• Look elsewhere if:

  • You need active maintenance or high-adoption packages (e.g., Symfony’s ErrorHandler or Laravel’s built-in exceptions).
  • Your project requires PHP < 7.4 (package dropped support in 2020).
  • You’re using non-PHP backends (e.g., Node.js, Go) or full-stack frameworks (e.g., Django, Rails).
  • You need advanced features:
    • Localization (e.g., translating error messages).
    • Nested exceptions or exception chaining.
    • Integration with monitoring tools (e.g., automatic Sentry event creation).
  • Your team prefers zero dependencies (this package adds ~2 classes to vendor/).
  • You’re building microservices where lightweight exceptions (e.g., Go’s errors.New) are preferred.

How to Pitch It (Stakeholders)

For Executives:

*"This package standardizes how our application handles errors, delivering three key benefits:

1. Faster Debugging: Engineers spend less time deciphering logs because technical details are automatically separated from user-facing messages.
2. Better User Experience: Customers see clear, actionable errors (e.g., ‘Your card was declined’) instead of cryptic 500 messages.
3. Scalable APIs: Consistent error formats reduce support costs and improve integration for partners/clients.

Investment: Minimal (a few hours to adopt). ROI: Hours saved monthly in debugging + reduced API churn. Risk: Low—if the package stalls, we can fork it in a day. Recommendation: Pilot in our payment module to validate impact before rolling out."*

For Engineering:

*"Problem: Our exceptions are a mess—some have user messages, others don’t; debug details leak to logs inconsistently; APIs return mixed error formats.

Solution: This package gives us a single source of truth for exceptions:

• BaseException: Enforces a public/debug message + HTTP status code structure.
• ExceptionContext: Lets us attach metadata (e.g., user_id, transaction_id) to errors without bloating classes.
• Zero Lock-in: Pure PHP, no Laravel/Symfony dependencies. Works alongside existing exceptions.

How We’d Use It:

1. New Exceptions: Extend BaseException (e.g., PaymentFailedException).
2. Existing Exceptions: Wrap with a trait to backport ExceptionContext.
3. API Responses: Update App\Exceptions\Handler to return structured JSON:

   return response()->json([
       'error' => $e->getPublicMessage(),
       'debug' => app()->debug() ? $e->getDebugMessage() : null,
   ], $e->getStatusCode());
   

Tradeoffs:

• Pros: Saves 10–20 hours/year in exception boilerplate; improves logs/APIs.
• Cons: Low-maintenance package (last update 2021), but the code is simple to fork.
• Risk: If we hit a snag, we can rewrite the 2 classes in a day.

Proposal: Let’s dogfood this in the checkout flow (high-error volume) and measure:

• Debugging time saved (track via Jira tickets).
• API error consistency (audit Swagger/OpenAPI specs). If it works, we’ll expand it to all custom exceptions in the next sprint."*

Key Talking Points:

• "This isn’t a framework—it’s a utility belt for exceptions. Like Carbon for dates, but for errors."
• "We’re not betting on this package’s future—we’re standardizing our own with minimal risk."
• "API clients and support teams will love the consistent error formats."