Exceptions Laravel Package

Getting Started

1. Install: Add via Composer: composer require spiral/exceptions
2. Basic usage: Start by using the provided base exception classes (DomainException, ValidationException, RuntimeException) to replace generic Exception in your domain layer.
3. First use case: Wrap a database call in a service with spiral/exceptions’ InfrastructureException to preserve context:

   try {
       $result = $this->db->fetch($sql);
   } catch (\PDOException $e) {
       throw new InfrastructureException('Failed to fetch user', 0, $e);
   }
   

4. Where to look first: Check src/Exceptions directory in the repo (if available) for class hierarchy and interface contracts like ExceptionInterface.
   • New: Explore the renderDebugState() method for debugging purposes (v1.2.2+).

Implementation Patterns

• Domain-specific exceptions: Extend DomainException to model business rule failures (e.g., UserAlreadyExistsException extends DomainException).
• Validation errors: Use ValidationException with structured data:

  throw new ValidationException([
      'email' => 'Already in use',
      'password' => 'Too short'
  ]);
  

• Exception wrapping: Always chain root causes using the third constructor parameter to retain stack trace integrity:

  throw new InfrastructureException('Payment failed', 0, $gatewayException);
  

• Error boundaries: Apply exception types as boundaries—e.g., catch ValidationException in controllers for 422 responses, and InfrastructureException for 5xx logs.
• Centralized handling: Integrate with Spiral’s error handler by mapping exception types to HTTP status codes in a custom ErrorHandler.
• Debug state rendering: Leverage renderDebugState() in development environments to output detailed exception context (e.g., validation errors, nested exceptions):

  if (app()->environment('local')) {
      echo (new ValidationException(['field' => 'Invalid']))->renderDebugState();
  }
  

Gotchas and Tips

• Stale package: Last major release was in 2019—verify compatibility with modern PHP versions (7.4–8.3) and Spiral 3.x/2.x. Test in a dev environment before adoption.
• No auto-inclusion: Unlike full frameworks, this package doesn’t hook into HTTP middleware automatically—you must wire it yourself (e.g., in global error handler or service provider).
• Extensibility: Extend exception classes to add context-specific methods (e.g., getErrorCode()) but keep them thin—avoid business logic in exceptions.
• Debugging: Use getPrevious() to traverse the exception chain. Log the last exception in the chain for root-cause visibility.
  • New: Utilize renderDebugState() for quick debugging in local/dev environments (avoid in production).
• Performance: Minimal overhead—exceptions are still thrown/catched normally, but the type hints reduce runtime checks (e.g., no instanceof sprawl).
• Missing features: No built-in translation, correlation IDs, or log formatting—pair with spiral/log or PSR-3 logger for rich diagnostics.
• Migration tip: When upgrading legacy apps, migrate step-by-step: first introduce typed exceptions in internal services, then wire to HTTP layer.
• Debug state caution: renderDebugState() may expose sensitive data—sanitize output for production-like environments or restrict usage to local/dev environments.