Flare Client Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/flare-client-php
   

   For Laravel projects, prefer spatie/laravel-flare instead.

2. Configuration: Add your Flare API key to .env:

   FLARE_API_KEY=your_api_key_here
   

3. First Use Case: Report an exception manually:

   use Spatie\FlareClient\Flare;
   
   try {
       // Risky code
   } catch (\Exception $e) {
       Flare::report($e);
   }
   

4. Automatic Error Handling: Register the error handler in your bootstrap file (e.g., bootstrap/app.php):

   Flare::registerErrorHandler();
   

Key Files to Review

• src/Flare.php – Core client class.
• src/Report.php – Report structure and customization.
• src/Collectors/ – Attribute collectors (e.g., Git, Request, Console).

Implementation Patterns

Core Workflows

1. Reporting Exceptions

// Basic report
Flare::report(new \RuntimeException('Oops!'));

// With custom context
Flare::report(new \RuntimeException('Oops!'))
    ->withContext(['user_id' => 123, 'action' => 'delete']);

2. Customizing Reports

$report = Flare::report(new \Exception('Custom report'))
    ->withGroupingOverride('FullStacktraceAndExceptionClassAndCode')
    ->withoutSensitiveData(['password', 'api_key'])
    ->withTraceContext(['custom_key' => 'value']);

3. Filtering Reports

Use a callback to filter reports before sending:

Flare::setReportFilter(function ($report) {
    return !in_array($report->exception->getCode(), [404, 500]);
});

4. Attribute Collectors

Extend or replace default collectors (e.g., for custom request data):

Flare::setRequestAttributeProvider(function ($request) {
    return ['custom_field' => $request->input('custom_field')];
});

5. Manual Tracing

Record custom spans or events:

$span = Flare::startSpan('database_query');
try {
    DB::query(...);
} finally {
    $span->end();
}

Integration Tips

Laravel-Specific

• Use spatie/laravel-flare for seamless Laravel integration (handles middleware, service providers, and more).
• For non-Laravel projects, manually register the error handler in your set_exception_handler or set_error_handler.

Symfony Integration

• Configure the HttpKernel to use Flare’s error handler:

  $kernel->getContainer()->set('flare.error_handler', Flare::errorHandler());
  

Testing

• Use Flare::testTrace() to simulate errors in tests:

  Flare::testTrace(function () {
      throw new \RuntimeException('Test error');
  });
  

Censoring Sensitive Data

• Censor request bodies, cookies, or sessions:

  Flare::setCensorRequestBody(true);
  Flare::setCensorCookies(['session', 'auth_token']);
  

Gotchas and Tips

Pitfalls

1. Double Reporting:

   • If both registerErrorHandler() and a custom set_exception_handler are used, errors may be reported twice. Disable the default handler if needed:

     Flare::registerErrorHandler(false); // Disables default error handler
     

2. Sensitive Data Leaks:

   • Always censor sensitive fields (e.g., passwords, tokens) in requests, cookies, or sessions. Use dot notation for nested arrays:

     Flare::setCensorRequestBodyFields(['user.password', '*.api_key']);
     

3. Performance Overhead:

   • Collecting Git info or stack traces can slow down requests. Disable unnecessary collectors:

     Flare::disableGitCollector();
     

4. Grouping Conflicts:

   • Custom grouping overrides (e.g., FullStacktraceAndExceptionClassAndCode) may reduce Flare’s ability to group similar errors. Use sparingly.

5. API Rate Limits:

   • Flare has rate limits. Avoid sending excessive reports (e.g., from cron jobs or background tasks). Use setReportFilter() to throttle reports.

Debugging Tips

1. Check API Responses:

   • Enable debug mode to log API errors:

     Flare::setDebugMode(true);
     

   • Inspect the flare.log file in your project root for API issues.

2. Verify API Key:

   • Ensure FLARE_API_KEY is correctly set in .env and not empty.

3. Network Issues:

   • If reports fail silently, check DNS resolution or proxy settings. Flare uses https://api.flareapp.io.

4. Stack Trace Issues:

   • If stack traces are incomplete, ensure FLARE_BASE_PATH is set to your project root:

     Flare::setBasePath(__DIR__);
     

Extension Points

1. Custom Collectors:

   • Implement Spatie\FlareClient\Collectors\CollectorInterface to add project-specific data:

     class CustomCollector implements CollectorInterface {
         public function collect(): array {
             return ['custom_data' => 'value'];
         }
     }
     Flare::addCollector(new CustomCollector());
     

2. Override Report Filtering:

   • Replace the default filter with a custom logic:

     Flare::setReportFilter(function ($report) {
         return $report->exception->getCode() !== 404;
     });
     

3. Modify API Sender:

   • Extend Spatie\FlareClient\Senders\ApiSender to customize HTTP requests (e.g., add headers):

     Flare::setApiSender(function () {
         return new class extends \Spatie\FlareClient\Senders\ApiSender {
             protected function getHeaders(): array {
                 return array_merge(parent::getHeaders(), ['X-Custom-Header' => 'value']);
             }
         };
     });
     

4. Disable Tracing for Specific Routes:

   • Use middleware to disable Flare for non-critical paths:

     Flare::disableTracing();
     

Configuration Quirks

1. Environment Variables:

   • Flare respects these env vars:
     • FLARE_API_KEY (required)
     • FLARE_DEBUG (enable debug logs)
     • FLARE_DISABLED (set to true to disable entirely)
     • FLARE_BASE_PATH (override project root for stack traces)

2. Laravel-Specific:

   • The Laravel package (spatie/laravel-flare) auto-configures most settings. Avoid mixing it with spatie/flare-client-php unless necessary.

3. PHP 8.5+:

   • Use declare(strict_types=1) to avoid deprecation warnings. The package is compatible with PHP 8.5 but may require type adjustments in custom code.

4. Git Collector:

   • The Git collector can be slow on CI/CD pipelines. Disable it if not needed:

     Flare::disableGitCollector();