Error Handler Laravel Package

Getting Started

Minimal Setup for Laravel Integration

1. Install the package (via Composer):

   composer require symfony/error-handler
   

2. Enable debugging in development (e.g., AppServiceProvider boot method):

   if (app()->environment('local', 'staging')) {
       \Symfony\Component\ErrorHandler\Debug::enable();
   }
   

3. First use case: Wrap risky operations (e.g., file I/O, external APIs):

   use Symfony\Component\ErrorHandler\ErrorHandler;
   
   $data = ErrorHandler::call(function () {
       return json_decode(file_get_contents('config.json'), true);
   });
   

4. Customize production errors (e.g., app/Exceptions/Handler.php):

   use Symfony\Component\ErrorHandler\HtmlErrorRenderer;
   
   HtmlErrorRenderer::setTemplate(__DIR__.'/../resources/views/errors/production.blade.php');
   

Implementation Patterns

1. Unified Error Handling Across Laravel Components

• APIs/Queues: Wrap HttpClient or queue jobs in ErrorHandler::call() to force exceptions:

  $response = ErrorHandler::call(function () use ($client) {
      return $client->get('https://api.example.com/data');
  });
  

• Service Containers: Register a global error handler in AppServiceProvider:

  \Symfony\Component\ErrorHandler\ErrorHandler::register();
  

2. Debugging Workflows

• Local Development: Enable full debugging:

  \Symfony\Component\ErrorHandler\Debug::enable();
  \Symfony\Component\ErrorHandler\DebugClassLoader::enable();
  

• Staging: Log errors to Sentry + show sanitized errors:

  if (app()->environment('staging')) {
      \Symfony\Component\ErrorHandler\ErrorHandler::register(
          new \Symfony\Component\ErrorHandler\ImpersonatingLogger(
              new \Sentry\Laravel\Integration\SentryLogger()
          )
      );
  }
  

3. Production Error Redaction

• Custom Error Templates: Extend HtmlErrorRenderer to mask sensitive data:

  HtmlErrorRenderer::setTemplate(function (Throwable $exception) {
      $trace = str_replace(['password=xxx', 'api_key=yyy'], '[REDACTED]', $exception->getTraceAsString());
      return view('errors.production', ['trace' => $trace]);
  });
  

• Laravel Integration: Override render() in App\Exceptions\Handler:

  public function render($request, Throwable $exception)
  {
      if ($this->shouldReturnJson($request, $exception)) {
          return parent::render($request, $exception);
      }
      return ErrorHandler::renderHtmlResponse($exception);
  }
  

4. CI/CD Quality Gates

• PHPUnit Tests: Fail on unhandled errors:

  use Symfony\Component\ErrorHandler\ErrorHandler;
  
  public function testCriticalPath()
  {
      $result = ErrorHandler::call(function () {
          // Risky operation
          return $this->service->processPayment();
      });
      $this->assertNotNull($result);
  }
  

• GitHub Actions: Add a step to scan for @-silenced errors:

  - name: Check for silenced errors
    run: |
      grep -r "@" --include="*.php" app/ || true
      if [ $? -eq 0 ]; then
        echo "::error::Silenced errors found. Use ErrorHandler::call() instead."
        exit 1
      fi
  

5. Legacy Code Modernization

• Deprecation Warnings: Log warnings during PHP 8+ migration:

  \Symfony\Component\ErrorHandler\ErrorHandler::register(
      new class implements \Symfony\Component\ErrorHandler\ErrorHandlerInterface {
          public function handle(Throwable $exception, bool $notify = true)
          {
              if ($exception instanceof \DeprecatedError) {
                  \Log::warning('Deprecation: ' . $exception->getMessage());
              }
              return false; // Let Laravel handle it
          }
      }
  );
  

Gotchas and Tips

Pitfalls

1. Double Error Handling:

   • Avoid mixing ErrorHandler::call() with Laravel’s try-catch. Use one or the other per operation.
   • Fix: Prefer ErrorHandler::call() for low-level operations (e.g., file I/O) and try-catch for business logic.

2. Debug Mode in Production:

   • Debug::enable() exposes full stack traces and sensitive paths. Never enable in production.
   • Fix: Use environment checks:

     if (!app()->environment('production')) {
         Debug::enable();
     }
     

3. Performance Overhead:

   • ErrorHandler::call() adds microsecond latency per call. Avoid wrapping high-frequency operations (e.g., loop iterations).
   • Fix: Reserve for critical paths (e.g., payments, auth).

4. Template Caching:

   • Custom HtmlErrorRenderer templates must be cached in production. Use Laravel’s blade cache:

     php artisan view:cache
     

5. Silenced Errors:

   • @ operator bypasses ErrorHandler::call(). Use ErrorHandler::call() instead:

     // Bad: Silenced error
     $data = @json_decode(file_get_contents('file.json'));
     
     // Good: Forced exception
     $data = ErrorHandler::call(function () {
         return json_decode(file_get_contents('file.json'));
     });
     

Debugging Tips

1. Stack Trace Analysis:

   • Use Debug::enable() to color-code stack traces and click file links in local/staging.

2. Autoloading Issues:

   • Enable DebugClassLoader::enable() to diagnose missing classes during development.

3. Custom Error Logging:

   • Extend ErrorHandlerInterface to log errors to external services (e.g., Datadog, Humio):

     ErrorHandler::register(new class implements ErrorHandlerInterface {
         public function handle(Throwable $exception, bool $notify)
         {
             \Log::critical('Custom error: ' . $exception->getMessage());
             return false; // Let Laravel handle it
         }
     });
     

4. Deprecation Warnings:

   • Filter warnings in php.ini to avoid noise:

     error_reporting = E_ALL & ~E_DEPRECATED
     

   • Re-enable only for critical paths using ErrorHandler::call().

Extension Points

1. Custom Error Renderers:

   • Implement ErrorRendererInterface for API responses or custom formats:

     use Symfony\Component\ErrorHandler\ErrorRendererInterface;
     
     class ApiErrorRenderer implements ErrorRendererInterface
     {
         public function render(Throwable $exception): string
         {
             return json_encode([
                 'error' => 'Server Error',
                 'code' => $exception->getCode(),
             ]);
         }
     }
     

2. Error Subscribers:

   • Hook into ErrorHandler::register() to modify exceptions before rendering:

     ErrorHandler::register(new class implements ErrorHandlerInterface {
         public function handle(Throwable $exception, bool $notify)
         {
             if ($exception instanceof \TypeError) {
                 $exception = new \RuntimeException('Type error: ' . $exception->getMessage());
             }
             return false;
         }
     });
     

3. Laravel Service Provider:

   • Bind ErrorHandler to Laravel’s container for dependency injection:

     $this->app->singleton(\Symfony\Component\ErrorHandler\ErrorHandlerInterface::class, function () {
         return new class implements ErrorHandlerInterface {
             // Custom logic
         };
     });
     

4. Queue Job Wrappers:

   • Create a base job class that wraps ErrorHandler::call():

     abstract class ErrorHandlingJob implements ShouldQueue
     {
         public function handle()
         {
             return ErrorHandler::call([$this, 'execute']);
         }
     
         abstract protected function execute();
     }