Airbrake Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Centric: The bundle is tightly coupled with Symfony’s event-driven architecture (e.g., ExceptionListener, ShutdownListener), making it a natural fit for Symfony applications. For Laravel, this requires abstraction via middleware, service providers, or event listeners to mimic Symfony’s kernel hooks.
• Error Reporting Focus: Aligns with Laravel’s built-in error handling (e.g., App\Exceptions\Handler) but lacks native integration with Laravel’s exception stack (e.g., throw_if, render). Custom middleware would be needed to bridge this gap.
• API Client Dependency: Relies on airbrake/phpbrake (v0.8.0+), which is PHP-agnostic but may require Laravel-specific context formatting (e.g., request data, route names).

Integration Feasibility

• High-Level Feasibility: Possible via:
  1. Middleware: Wrap phpbrake in Laravel middleware to catch exceptions globally.
  2. Service Provider: Register phpbrake as a Laravel service and bind it to exception handling.
  3. Event Listeners: Use Laravel’s Illuminate\Contracts\Debug\ExceptionHandler to forward exceptions to phpbrake.
• Key Challenges:
  • Symfony’s Kernel events (e.g., kernel.exception) don’t map 1:1 to Laravel’s ExceptionHandler. Custom logic will be needed to replicate behavior (e.g., ignoring HttpException).
  • No Native Laravel Support: The bundle assumes Symfony’s dependency injection (DI) container, requiring manual service binding in Laravel.

Technical Risk

Key Questions

1. Exception Scope:

   • Should the bundle report all exceptions (including CLI commands, queues) or only HTTP-related ones?
   • How to handle Laravel’s render() method vs. Symfony’s ExceptionListener?

2. Context Enrichment:

   • What Laravel-specific data should be included in Airbrake notices? (e.g., authenticated user, request headers, debug mode flag).

3. Error Ignoring:

   • How to replicate Symfony’s ignored_exceptions (e.g., HttpException) in Laravel’s ExceptionHandler?

4. Testing Strategy:

   • How to mock phpbrake in Laravel’s testing environment (e.g., HttpTests) without hitting Airbrake’s API?

5. Upgrade Path:

   • If airbrake/phpbrake evolves, how will Laravel’s integration adapt (e.g., breaking changes in v1.0)?

Integration Approach

Stack Fit

• Laravel Compatibility:

  • PHP Version: Requires PHP 7.2+ (Laravel 8+ supports this).
  • Dependencies: airbrake/phpbrake@0.8.0 is compatible with Laravel’s ecosystem (no conflicts with Illuminate).
  • Service Container: Laravel’s DI container can host phpbrake services, but Symfony’s EventDispatcher must be emulated via Laravel’s events or middleware.

• Alternatives Considered:

  • Native Laravel Packages: Packages like spatie/laravel-airbrake offer tighter integration but may lack Airbrake API v3 features.
  • Direct phpbrake Usage: Avoid the bundle entirely and use phpbrake directly with custom middleware (lower abstraction overhead).

Migration Path

1. Phase 1: Proof of Concept (PoC)

   • Install airbrake/phpbrake via Composer.
   • Create a custom middleware to catch exceptions and forward them to phpbrake.
   • Test with a single route to validate exception reporting.

2. Phase 2: Full Integration

   • Service Provider: Bind phpbrake as a Laravel service with config from .env (e.g., AIRBRAKE_PROJECT_ID).
   • Exception Handler: Extend App\Exceptions\Handler to delegate non-ignored exceptions to phpbrake.
   • Middleware: Add to $middleware (global) or $routeMiddleware (selective routes).
   • Context Enrichment: Modify phpbrake notices to include Laravel-specific data (e.g., request()->route(), auth()->user()).

3. Phase 3: Configuration & Ignoring

   • Replicate ignored_exceptions logic in ExceptionHandler (e.g., ignore HttpException).
   • Add .env support for host, project_id, and project_key.

Compatibility

Sequencing

1. Prerequisites:

   • Laravel 8+ (PHP 7.2+).
   • airbrake/phpbrake@0.8.0 installed.
   • Airbrake/Errbit project configured.

2. Order of Implementation:

   • Step 1: Basic middleware to log exceptions to phpbrake.
   • Step 2: Add .env configuration and service binding.
   • Step 3: Implement exception filtering (ignore list).
   • Step 4: Enrich notices with Laravel context.
   • Step 5: Test edge cases (CLI, queues, ignored exceptions).

3. Dependencies:

   • phpbrake must be initialized after Laravel’s bootstrap (e.g., in a service provider’s boot()).
   • Middleware must run after Laravel’s ConvertEmptyStringsToNullMiddleware to capture raw exceptions.

Operational Impact

Maintenance

• Pros:
  • MIT License: No legal restrictions.
  • Active Underlying Library: airbrake/phpbrake is maintained (check for updates).
  • Minimal Boilerplate: Middleware/service provider approach keeps changes localized.
• Cons:
  • Custom Logic: Exception filtering and context enrichment require ongoing maintenance.
  • Dependency on phpbrake: Future API changes may break integration.
• Tooling:
  • Use Laravel’s config:cache to optimize service binding.
  • Monitor Airbrake’s API rate limits (e.g., queue delays if hitting limits).

Support

• Debugging:
  • Exception Flow: Trace exceptions from Laravel’s ExceptionHandler → middleware → phpbrake.
  • Logging: Add debug logs for phpbrake initialization and notice sending.
• Common Issues:
  • Silent Failures: phpbrake may fail silently; add retry logic or fallback logging.
  • Context Missing: Validate that Laravel-specific data (e.g., route) is included in notices.
• Support Channels:
  • Primary: GitHub issues for airbrake/phpbrake.
  • Secondary: Laravel Discord/Forums for integration-specific questions.

Scaling

• Performance:
  • Low Overhead: phpbrake adds ~50ms per exception (negligible for most apps).
  • Batch Processing: For high-volume apps, consider buffering exceptions and sending in batches (e.g., via queue).
• Horizontal Scaling:
  • Stateless: Middleware/service provider is stateless; scales with Laravel’s architecture.
  • Rate Limiting: Airbrake’s API may throttle requests; implement exponential backoff in middleware.
• Monitoring:
  • Track phpbrake success/failure rates via Laravel’s logging or a custom metric (e.g., laravel-airbrake-sent).

Failure Modes