Flare Client Php Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer:

   composer require facade/flare-client-php
   

2. Publish the config (optional but recommended for customization):

   php artisan vendor:publish --provider="Facade\FlareClient\FlareServiceProvider" --tag="config"
   

3. Configure .env with your Flare API key:

   FLARE_API_KEY=your_api_key_here
   

4. First use case: Report an exception in a Laravel controller or middleware:

   use Facade\FlareClient\Flare;
   
   try {
       // Risky operation
   } catch (\Exception $e) {
       Flare::report($e); // Send to Flare
       throw $e; // Re-throw or handle locally
   }
   

Where to Look First

• Service Provider: FlareServiceProvider (handles auto-registration in Laravel).
• Facade: Flare (primary entry point for reporting).
• Config: config/flare.php (API key, endpoint, environment filtering).
• Documentation: GitHub README (if available) or inline PHPDoc.

Implementation Patterns

Core Workflows

1. Exception Reporting

• Basic reporting:

  Flare::report(new \Exception("Oops!"));
  

• With context (e.g., user ID, request data):

  Flare::report($e)
       ->context([
           'user_id' => auth()->id(),
           'request_data' => request()->all(),
       ]);
  

2. Breadcrumbs for Tracing

Add contextual events leading to an error:

Flare::breadcrumb('User clicked "Submit"');
Flare::breadcrumb('Processing order #123', [
    'order_id' => 123,
    'status' => 'pending',
]);

3. Middleware Integration

Automatically report uncaught exceptions in Laravel:

use Facade\FlareClient\Flare;

class ReportExceptions
{
    public function handle($request, Closure $next)
    {
        try {
            return $next($request);
        } catch (\Exception $e) {
            Flare::report($e);
            throw $e;
        }
    }
}

4. Logging Integration

Attach logs to errors for deeper context:

Flare::report($e)
     ->withLogs([
         'query' => 'SELECT * FROM users WHERE id = 1',
         'result' => $users,
     ]);

5. Environment Filtering

Disable reporting in local environments via config:

'environments' => ['production', 'staging'],

Integration Tips

• Laravel Ignition: Use alongside Ignition for local development (Flare handles production).
• Queue Delay: For performance, report errors asynchronously:

  Flare::report($e)->later(); // Uses Laravel's queue
  

• Custom Metadata: Attach structured data (e.g., feature flags, A/B test variants):

  Flare::report($e)->context(['feature_flags' => ['new_ui' => true]]);
  

Gotchas and Tips

Pitfalls

1. API Key Leaks:

   • Never commit .env or hardcode keys in version control.
   • Use Laravel’s env() helper or config files for keys.

2. Sensitive Data in Context:

   • Avoid logging PII (passwords, tokens) in context() or withLogs().
   • Use Flare::report($e)->mask() to redact sensitive fields:

     Flare::report($e)->mask(['password', 'credit_card']);
     

3. Performance Overhead:

   • Reporting errors synchronously can slow down requests. Use ->later() for production.
   • Disable in local environments to avoid noise.

4. Environment Mismatches:

   • Ensure FLARE_ENVIRONMENT in .env matches your Flare dashboard setup.
   • Defaults to production if unset.

5. Breadcrumb Limits:

   • Flare may truncate long breadcrumb trails. Keep messages concise.

Debugging

• Check Config: Verify config/flare.php for correct API key/endpoint.
• Network Tab: Inspect XHR requests to https://flareapp.io/api/v1/errors for failures.
• Log Errors: Enable Laravel’s APP_DEBUG=true to see if exceptions are caught before Flare.

Extension Points

1. Custom Transport: Override the HTTP client for proxy support or retries:

   Flare::setTransport(new CustomHttpClient());
   

2. Event Listeners: Hook into flare.reporting event to modify payloads:

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

3. Queue Failures: Handle failed queue jobs for ->later() reports:

   Flare::report($e)->later()->onFailure(function ($job, $exception) {
       Log::error("Flare report failed: " . $exception->getMessage());
   });
   

Config Quirks

• Endpoint Override: Change the default Flare endpoint in config:

  'endpoint' => 'https://your-custom-flare-endpoint/api/v1/errors',
  

• SSL Verification: Disable for self-signed certs (not recommended for production):

  'verify_ssl' => false,
  

• Rate Limiting: Flare may throttle requests. Implement exponential backoff in custom transport if needed.