Flare Debug Sender Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/flare-debug-sender
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Spatie\FlareDebugSender\FlareDebugSenderServiceProvider" --tag="config"
   

2. First Use Case:

   • Register the debug sender in config/flare.php:

     'senders' => [
         // ...
         \Spatie\FlareDebugSender\FlareDebugSender::class,
     ],
     

   • Trigger a debug payload via Flare (e.g., php artisan flare:debug or Flare::debug() in code).
   • Check the debug output in your terminal or configured log location (e.g., storage/logs/flare-debug.log).

3. Where to Look First:

   • Config: config/flare.php (ensure the sender is enabled).
   • Logs: storage/logs/flare-debug.log (default output location).
   • Service Provider: Spatie\FlareDebugSender\FlareDebugSenderServiceProvider (for bootstrapping).

Implementation Patterns

Core Workflows

1. Debugging Flare Payloads Locally:

   • Use Flare::debug() in your code to capture payloads without sending them to the Flare server.
   • Example:

     use FlareClient\Flare;
     Flare::debug('User login failed', ['user_id' => 123]);
     

   • Payloads are logged to storage/logs/flare-debug.log in JSON format.

2. Integration with Laravel Exceptions:

   • Extend Laravel’s exception handling to log Flare payloads automatically:

     use Illuminate\Foundation\Exceptions\Handler;
     use Spatie\FlareDebugSender\FlareDebugSender;
     
     public function report(Throwable $exception)
     {
         FlareDebugSender::send($exception);
         parent::report($exception);
     }
     

3. Conditional Debugging:

   • Enable/disable the sender dynamically via config or environment variables:

     // In config/flare.php
     'flare_debug_sender' => env('FLARE_DEBUG_SENDER_ENABLED', false),
     

   • Toggle with:

     php artisan config:set flare.flare_debug_sender true
     

4. Custom Payload Formatting:

   • Override the default payload formatter by binding a custom formatter to the container:

     $this->app->bind(\Spatie\FlareDebugSender\PayloadFormatter::class, function () {
         return new CustomPayloadFormatter();
     });
     

5. Testing Workflow:

   • Use the sender in PHPUnit tests to verify Flare payloads:

     public function testFlarePayload()
     {
         Flare::debug('Test payload');
         $this->assertFileExists(storage_path('logs/flare-debug.log'));
     }
     

Gotchas and Tips

Pitfalls

1. Log File Overwrite:

   • The debug log (flare-debug.log) is appended to by default. Ensure your testing environment doesn’t fill up storage with redundant logs.
   • Fix: Configure log rotation or truncate the file before tests:

     File::put(storage_path('logs/flare-debug.log'), '');
     

2. Missing Config Key:

   • If the sender isn’t registered in config/flare.php, payloads will silently fail to log.
   • Fix: Verify the sender is listed under 'senders':

     'senders' => [
         \Spatie\FlareDebugSender\FlareDebugSender::class,
     ],
     

3. Payload Size Limits:

   • Large payloads (e.g., nested arrays, large variables) may cause log bloat.
   • Tip: Use Flare::debug()->withData(['key' => 'value']) sparingly or sanitize data:

     Flare::debug('Large data', ['user' => collect($user)->only(['id', 'name'])]);
     

4. Race Conditions in Testing:

   • If multiple tests trigger Flare payloads, logs may interleave unpredictably.
   • Fix: Use unique log files per test or clear logs between tests:

     $this->artisan('config:set flare.flare_debug_sender_log=storage/logs/test-flare.log');
     

Debugging Tips

1. Verify Sender Registration:

   • Check if the sender is active:

     php artisan flare:debug
     

   • Look for output in the terminal or log file.

2. Log Format Inspection:

   • Payloads are logged as JSON. Use jsonlint.com to validate the output if issues arise.

3. Environment-Specific Config:

   • Disable the sender in production by default:

     'flare_debug_sender' => app()->environment('local'),
     

4. Custom Log Path:

   • Override the log path in config:

     'flare_debug_sender_log' => storage_path('logs/custom-flare-debug.log'),
     

Extension Points

1. Custom Payload Formatter:

   • Implement Spatie\FlareDebugSender\Contracts\PayloadFormatter to modify payload structure:

     class CustomFormatter implements PayloadFormatter {
         public function format(array $payload): string
         {
             return json_encode($payload, JSON_PRETTY_PRINT);
         }
     }
     

2. Pre-Send Hooks:

   • Use Laravel’s service container to intercept payloads before logging:

     $this->app->afterResolving(\Spatie\FlareDebugSender\FlareDebugSender::class, function ($sender) {
         $sender->setPayloadModifier(function ($payload) {
             $payload['custom_key'] = 'intercepted';
             return $payload;
         });
     });
     

3. Log to External Services:

   • Extend the sender to forward logs to Slack, Datadog, etc.:

     class SlackFlareDebugSender extends FlareDebugSender {
         public function send(array $payload)
         {
             parent::send($payload);
             $this->notifySlack($payload);
         }
     
         protected function notifySlack(array $payload)
         {
             // Slack API logic here
         }
     }