Exceptions Laravel Package

Product Decisions This Supports

• Consistent Error Handling in Laravel: Standardize error handling across the application by converting PHP native errors (e.g., E_WARNING, E_NOTICE) into structured exceptions, aligning with Laravel’s exception-driven workflow (e.g., try/catch blocks, middleware like App\Exceptions\Handler).
• Debugging & Observability: Enable richer error context (stack traces, payloads) for tools like Sentry, Laravel Debugbar, or custom logging, improving incident response.
• Deprecation Warnings as Exceptions: Flag deprecations (e.g., PHP 8.1+ warnings) as exceptions in CI/CD pipelines to enforce proactive fixes, reducing technical debt.
• Testing & Mocking: Simplify unit/integration tests by replacing set_error_handler() with exception-based assertions (e.g., expectException(\ErrorException)).
• Roadmap for PHP 8+ Features: Prepare for stricter error handling (e.g., E_DEPRECATED as fatal by default in PHP 9), reducing migration friction.
• Build vs. Buy: Avoid reinventing error-handling logic (e.g., custom set_error_handler() wrappers) by leveraging a battle-tested, specification-compliant solution.

When to Consider This Package

• Avoid if:
  • The project does not use Laravel or relies on native PHP error suppression (@ operator) heavily.
  • You need active maintenance (package is archived; consider alternatives like symfony/error-handler or Laravel’s built-in ErrorException).
  • Your team prefers custom error formatting (e.g., JSON API responses) over exception-based handling.
  • The app is PHP 7.4 or lower (package may not support older versions).
• Consider alternatives if:
  • You want real-time error display (use Laravel’s debugbar or laravel-debug-exceptions).
  • You need HTTP-specific error handling (e.g., converting errors to 500 responses; use middleware like App\Exceptions\Handler).
  • The team lacks exception-handling familiarity (may require training).

How to Pitch It (Stakeholders)

For Executives: "This package standardizes how PHP errors are handled across our Laravel apps—turning cryptic notices/warnings into actionable exceptions. It’s like adding seatbelts to our error-handling system: fewer crashes (unhandled errors), easier debugging, and proactive fixes for deprecations. Low risk (MIT license), zero maintenance (we own the integration), and aligns with our shift-left testing goals. Estimated ROI: 20% faster incident resolution."

For Engineering: *"We’re replacing ad-hoc set_error_handler() calls with a spec-compliant exception handler. Benefits:

• Consistency: All errors (even deprecations) become exceptions, play nice with Laravel’s App\Exceptions\Handler.
• Tooling: Works seamlessly with Sentry, Debugbar, and custom loggers.
• Testing: Mock errors as exceptions (e.g., expectException(\ErrorException)).
• Future-proof: Handles PHP 8+ deprecations as exceptions in CI. Tradeoff: Archived package, but we control the integration. Alternatives like symfony/error-handler exist but add complexity. Recommend a 2-week spike to validate."*

For Developers: *"No more hunting for E_NOTICE logs—errors become exceptions you can catch. Example:

try {
    trigger_error('Oops!');
} catch (\ErrorException $e) {
    report($e); // Integrates with Laravel’s reporting.
}

Enable deprecation-as-exceptions in CI with PHP_ERROR_EXCEPTION_DEPRECATIONS=1. Bypass in tests with PHP_ERROR_EXCEPTIONS=0."*