Flare Debug Sender Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require spatie/flare-debug-sender
   

2. Publish Flare config (if not already done):

   php artisan vendor:publish --tag=flare-config
   

3. Configure in config/flare.php:

   'sender' => [
       'class' => \Spatie\FlareDebugSender\FlareDebugSender::class,
       'config' => [
           'channel' => \Spatie\FlareDebugSender\Channels\RayDebugChannel::class,
           'passthrough_errors' => true,
       ],
   ],
   

4. Trigger a test payload (e.g., via Tinker or a route):

   \Flare::send(new \Exception('Test error for debugging'));
   

First Use Case: Local Error Simulation

Use this to reproduce production-like errors without deploying to staging. Example:

// Simulate a failed API call
$exception = new \Exception('Failed to fetch from third-party API', 0, null, 'https://api.example.com/endpoint');
\Flare::send($exception);

Check Ray for the formatted payload.

Implementation Patterns

Core Workflow: Debugging Flare v3 Payloads

1. Configure the sender in flare.php with your preferred channel (e.g., RayDebugChannel for visual debugging).
2. Send test payloads via:
   • Manual exceptions (e.g., throw new \Exception('Debug me');).
   • Custom logic (e.g., simulate API failures, race conditions).
   • Automated tests (e.g., phpunit with Flare::send() in assertions).
3. Inspect outputs:
   • Ray: Visualize traces, context, and payload structure.
   • Logs/Files: Use LaravelLogDebugChannel or FileDebugChannel for non-interactive debugging.

Integration Tips

• Pair with Laravel Exceptions: Extend Handler to auto-send Flare payloads for specific exceptions:

  public function register()
  {
      $this->renderable(function (\Some\CustomException $e) {
          \Flare::send($e);
          return response()->view('errors.custom');
      });
  }
  

• Test Custom Error Handlers: Validate middleware/handlers that modify Flare payloads:

  // Test middleware
  $payload = \Flare::send(new \Exception('Test'))->getPayload();
  $this->assertArrayHasKey('custom_field', $payload['context']);
  

• Mock External Services: Simulate third-party API failures:

  \Mockery::mock('overload:' . ThirdPartyClient::class)
      ->shouldReceive('fetch')
      ->andThrow(new \Exception('Mocked API failure'));
  \Flare::send(new \Exception('API call failed'));
  

Advanced: Custom Channels

Extend \Spatie\FlareDebugSender\Channels\DebugChannel to integrate with:

• Slack/Teams: Log payloads to chat apps.
• Databases: Store debug payloads for later analysis.
• Custom UIs: Build a dashboard for Flare debugging.

Example:

class SlackDebugChannel extends DebugChannel
{
    public function log(string $message): void
    {
        $webhook = new \GuzzleHttp\Client();
        $webhook->post('https://hooks.slack.com/...', [
            'json' => ['text' => $message],
        ]);
    }
}

Gotchas and Tips

Pitfalls

1. Payload Size Limits:

   • Large payloads (e.g., deep traces) may hit Ray’s UI limits. Use print_full_payload: false to debug incrementally.
   • Fix: Filter context data or use FileDebugChannel for large payloads.

2. SSL Verification:

   • Disabling SSL verification (CURLOPT_SSL_VERIFYPEER => 0) is required for local testing but unsafe for production. Ensure this is not committed to shared repos.
   • Fix: Use environment-specific config:

     'sender_config' => [
         'curl_options' => config('app.debug') ? [
             CURLOPT_SSL_VERIFYPEER => 0,
         ] : [],
     ],
     

3. Channel-Specific Quirks:

   • RayDebugChannel: Requires Ray to be running (php artisan ray:start). Debugging fails silently if Ray isn’t active.
   • FileDebugChannel: Permissions issues may block writes. Use storage_path('logs/flare-debug.log') for Laravel-friendly paths.
   • LaravelLogDebugChannel: Logs appear in storage/logs/laravel.log but may be overwhelmed in high-traffic apps.

4. Passthrough Behavior:

   • passthrough_errors: true sends payloads to both the debug channel and the default Flare sender. Disable this in production-like tests to avoid duplicate payloads.

Debugging Tips

1. Inspect Raw Payloads: Use print_full_payload: true to debug payload structure, then disable it for cleaner output:

   'config' => [
       'print_full_payload' => env('DEBUG_FLARE_RAW') === 'true',
   ],
   

2. Trace ID Replacement: Enable replace_tracing_ids: true to humanize trace IDs in logs (e.g., span-123 → span-abc). Useful for correlating logs across services.

3. Time Formatting: replace_tracing_times: true converts timestamps to relative durations (e.g., 100ms), making performance debugging easier.

4. Endpoint/Resource Printing: Use print_endpoint: true or print_resource: true to highlight which API routes or database queries triggered the error.

Extension Points

1. Custom Senders: Replace CurlSender with a queue-based sender for async debugging:

   'sender' => \Spatie\FlareDebugSender\Senders\QueueSender::class,
   'sender_config' => [
       'queue' => 'flare-debug',
   ],
   

   Implement \Spatie\FlareDebugSender\Sender to add support for:

   • gRPC: For microservices.
   • WebSockets: Real-time debugging.
   • Database: Store payloads for offline analysis.

2. Payload Filtering: Override \Spatie\FlareDebugSender\FlareDebugSender::preparePayload() to:

   • Redact sensitive data (e.g., passwords, tokens).
   • Add custom metadata (e.g., Git commit hash, environment).

   protected function preparePayload(array $payload): array
   {
       $payload['context']['debug'] = [
           'environment' => app()->environment(),
           'commit' => shell_exec('git rev-parse --short HEAD'),
       ];
       return $payload;
   }
   

3. Conditional Debugging: Use Laravel’s service providers to enable debugging only in specific environments:

   if (app()->environment('local')) {
       $this->app->bind(\Spatie\Flare\Flare::class, function () {
           $flare = new \Spatie\Flare\Flare();
           $flare->sendUsing(\Spatie\FlareDebugSender\FlareDebugSender::class, [/* config */]);
           return $flare;
       });
   }