Liferaft Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/liferaft
   

   Add the service provider to config/app.php under providers:

   Laravel\Liferaft\LiferaftServiceProvider::class,
   

2. Publish Config:

   php artisan vendor:publish --provider="LiferaftServiceProvider" --tag="liferaft-config"
   

   This generates config/liferaft.php with default settings.

3. First Use Case: Trigger a bug report from an exception handler (e.g., app/Exceptions/Handler.php):

   use Laravel\Liferaft\Liferaft;
   
   public function report(Throwable $exception)
   {
       Liferaft::report($exception);
       // Parent report logic...
   }
   

Implementation Patterns

Core Workflow

1. Reporting Exceptions:

   try {
       // Risky operation
   } catch (Throwable $e) {
       Liferaft::report($e, [
           'user_id' => auth()->id(),
           'context' => ['key' => 'value'],
       ]);
   }
   

   • Attach metadata via the second argument (e.g., user ID, request data).

2. Manual Reports:

   Liferaft::report(new \RuntimeException('Custom error'), [
       'custom_data' => 'foo',
   ]);
   

3. Conditional Reporting:

   if (app()->environment('production')) {
       Liferaft::report($exception);
   }
   

Integration Tips

• Middleware: Use Liferaft::report() in middleware to catch unhandled exceptions:

  public function handle($request, Closure $next)
  {
      try {
          return $next($request);
      } catch (Throwable $e) {
          Liferaft::report($e);
          throw $e; // Re-throw for other handlers
      }
  }
  

• Artisan Commands: Report errors from CLI commands:

  try {
      // Command logic
  } catch (Throwable $e) {
      Liferaft::report($e);
      $this->error('Failed. Report sent.');
  }
  

• Queue Workers: Wrap queue jobs in try-catch blocks and report failures:

  try {
      $job->handle();
  } catch (Throwable $e) {
      Liferaft::report($e, ['job' => get_class($job)]);
      throw $e;
  }
  

Gotchas and Tips

Pitfalls

1. Double Reporting:

   • Ensure Liferaft::report() isn’t called in both Handler.php and middleware for the same exception.
   • Fix: Use a flag (e.g., exception->liferaft_reported) to avoid duplicates.

2. Sensitive Data Leakage:

   • Avoid attaching raw request->all() or session data to reports.
   • Fix: Sanitize payloads:

     Liferaft::report($e, [
         'user_id' => auth()->id(),
         'ip' => request()->ip(),
         // Avoid: 'password' => request()->input('password'),
     ]);
     

3. Rate Limiting:

   • Excessive reports may trigger rate limits (e.g., GitHub API).
   • Fix: Configure config/liferaft.php:

     'rate_limit' => 5, // Max reports per minute
     

4. Environment-Specific Issues:

   • Reports may fail silently in non-production environments if misconfigured.
   • Fix: Test with app()->environment('local') checks.

Debugging

• Log Locally: Enable local logging in config/liferaft.php:

  'log_locally' => true,
  

  Check storage/logs/liferaft.log for failed reports.

• Verify Webhook: Use php artisan liferaft:test to simulate a report and validate the webhook endpoint.

Extension Points

1. Custom Payloads: Override the payload structure via a service provider:

   Liferaft::extend(function ($payload, $exception) {
       $payload['custom_field'] = 'value';
       return $payload;
   });
   

2. Transport Layer: Replace the default GitHub/GitLab reporter by binding a custom Liferaft\Reporter implementation:

   $this->app->bind(Liferaft\Reporter::class, function () {
       return new CustomReporter();
   });
   

3. Event Listeners: Listen for liferaft.reporting events to modify reports:

   Liferaft::reporting(function ($report) {
       $report->payload['extra'] = 'data';
   });