Flare Client Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/flare-client-php
   

   Ensure your PHP version is 8.2+.

2. Basic Initialization:

   use Spatie\FlareClient\Flare;
   
   $flare = Flare::make('YOUR_FLARE_API_KEY');
   

3. First Use Case: Capture an exception:

   try {
       // Risky code
   } catch (\Exception $e) {
       $flare->report($e);
   }
   

4. For Laravel: Use the dedicated Laravel package instead, which integrates seamlessly with Laravel’s error handling.

Implementation Patterns

Core Workflows

1. Error Reporting

• Exceptions:

  $flare->report(new \RuntimeException('Oops!'));
  

• Errors:

  $flare->reportError(new \Error('Division by zero'));
  

2. Logging

Use the dedicated logger for structured logs:

$flare->logger()->error('User login failed', ['user_id' => 123]);

Supports Monolog’s Level enum (e.g., debug(), info(), warning()).

3. Tracing

• Manual Spans:

  $span = $flare->tracer()->startSpan('database_query');
  $span->end();
  

• Subtasks: Automatically attach jobs/commands to parent traces:

  $flare->tracer()->startSubtask('checkout_process');
  

4. Sampling

Control trace collection with dynamic rules:

$flare->sampler()->addRule(
    new \Spatie\FlareClient\Sampling\SamplingRule(
        entryPoint: 'CheckoutController',
        percentage: 100.0,
    )
);

5. Attribute Providers

Customize data collection via providers (e.g., for requests, users):

$flare->setRequestAttributesProvider(
    fn (\Symfony\Component\HttpFoundation\Request $request) => [
        'custom_field' => $request->get('custom_data'),
    ]
);

Integration Tips

Laravel-Specific

• Middleware: Use FlareMiddleware to auto-capture HTTP errors.
• Queue Jobs: Enable JobRecorder to trace queue workers:

  $flare->jobRecorder()->record($job);
  

Non-Laravel Frameworks

• Symfony: Integrate with HttpKernel events for request/response tracing.
• Custom Apps: Manually trigger traces/logs in critical paths (e.g., CLI commands):

  $flare->tracer()->startSpan('cli_command')->end();
  

Performance

• Batch Processing: Use DaemonSender (bundled) for local buffering:

  $flare->setSender(new \Spatie\FlareClient\Sender\DaemonSender());
  

• Sampling: Reduce overhead by sampling low-priority traces (e.g., health checks at 0%).

Gotchas and Tips

Pitfalls

1. Double Reporting:

   • Avoid calling $flare->report() in both try/catch blocks and global error handlers (e.g., set_exception_handler). Use Flare::make() once and reuse the instance.

2. Sampling Conflicts:

   • Dynamic samplers override static rules. Test sampling logic in staging to avoid missing critical traces.

3. Sensitive Data Leaks:

   • Always censor PII (e.g., passwords, tokens) using attribute providers:

     $flare->setRequestAttributesProvider(
         fn ($request) => array_filter($request->request->all(), fn ($key) => !str_starts_with($key, 'password'))
     );
     

   • Use wildcard censoring for nested data:

     $flare->censor('user.*', 'payment.*');
     

4. Trace Context:

   • Disabled tracing ($flare->disableTracing()) must be called before starting spans to avoid leaks.

5. Deprecated Methods:

   • Avoid reportMessage() (replaced by $flare->logger()).
   • Old traits (SpanTrait, SpanEventTrait) are deprecated; use dedicated recorder classes.

Debugging

1. Local Testing:

   • Use flare:test command to simulate errors:

     php artisan flare:test --error="Division by zero"
     

2. Sender Issues:

   • Check DaemonSender logs if Flare reports aren’t reaching the server. Fallback to CurlSender:

     $flare->setSender(new \Spatie\FlareClient\Sender\CurlSender());
     

3. Sampling Debugging:

   • Log sampler decisions:

     $flare->sampler()->shouldSample($entryPoint, $parentSampled);
     

4. Attribute Overrides:

   • Verify providers are registered early in the app lifecycle (e.g., service container bootstrapping).

Extension Points

1. Custom Recorders: Extend Recorder to add domain-specific data (e.g., database queries):

   class CustomRecorder implements \Spatie\FlareClient\Recorder\Recorder
   {
       public function record(\Spatie\FlareClient\EntryPoint $entryPoint): void
       {
           // Add custom spans/logs
       }
   }
   $flare->addRecorder(new CustomRecorder());
   

2. Attribute Providers: Implement interfaces like RequestAttributesProvider to inject app-specific metadata:

   class AppUserProvider implements \Spatie\FlareClient\AttributeProvider\UserAttributesProvider
   {
       public function getAttributes(): array
       {
           return ['user_role' => auth()->user()->role];
       }
   }
   $flare->setUserAttributesProvider(new AppUserProvider());
   

3. Lifecycle Hooks: Reset state between requests (e.g., in middleware):

   $flare->lifecycle()->reset();
   

4. Grouping Overrides: Customize error grouping (e.g., by exception class + code):

   $flare->setGroupingOverride(
       \Spatie\FlareClient\Grouping\GroupingOverride::fullStacktraceAndExceptionClassAndCode()
   );