Flare Client Php Laravel Package

## Getting Started

### Minimal Setup
1. **Install the package** via Composer:
   ```bash
   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 with new filtering support:

   use Facade\FlareClient\Flare;
   
   try {
       // Risky operation
   } catch (\Exception $e) {
       Flare::report($e)
            ->filter(function (\Exception $e) {
                return $e instanceof \RuntimeException; // Custom filter logic
            });
       throw $e;
   }
   

Where to Look First

• Service Provider: FlareServiceProvider (handles auto-registration in Laravel).
• Facade: Flare (primary entry point for reporting, now with programmatic filtering).
• Config: config/flare.php (API key, endpoint, new: comprehensive filtering rules).
• Documentation: GitHub README (updated with filtering features and examples).

Implementation Patterns

Core Workflows

1. Exception Reporting with Filtering

• Basic reporting with config-based filtering:

  Flare::report(new \Exception("Oops!")); // Respects config/flare.php filter rules
  

• Programmatic filtering (overrides config):

  Flare::report($e)
       ->filter(function (\Exception $e) {
           return strpos($e->getMessage(), 'critical') !== false;
       });
  

2. Advanced Filtering Strategies

• Type-based filtering (config):

  'filter' => [
      'types' => [\RuntimeException::class, \InvalidArgumentException::class],
  ],
  

• Message pattern matching (config):

  'filter' => [
      'messages' => ['*Timeout*', '*Connection*'],
  ],
  

• Combined filtering (config + programmatic):

  'filter' => [
      'callback' => function (\Exception $e) {
          return app()->environment('production');
      },
  ];
  Flare::report($e)->filter(function (\Exception $e) {
      return $e->getCode() === 500; // Override config
  });
  

3. Breadcrumbs with Filter Awareness

Add context while respecting filtering:

Flare::breadcrumb('User action', ['step' => 'checkout'])
     ->filter(function ($breadcrumb) {
         return !app()->environment('local'); // Skip in local
     });

4. Middleware Integration with Filtering

Automatically report and filter exceptions:

class ReportFilteredExceptions
{
    public function handle($request, Closure $next)
    {
        try {
            return $next($request);
        } catch (\Exception $e) {
            Flare::report($e)
                 ->filter(function (\Exception $e) use ($request) {
                     return $request->ip() !== '127.0.0.1'; // Skip local IPs
                 });
            throw $e;
        }
    }
}

5. Environment-Specific Filtering

Leverage Laravel environments in filters:

Flare::report($e)->filter(function (\Exception $e) {
    return app()->environment(['staging', 'production']);
});

6. Dynamic Filtering via Extenders

Modify payloads before filtering occurs:

Flare::extend(function ($payload) {
    $payload['is_critical'] = strpos($payload['exception']['message'], 'critical') !== false;
    return $payload;
});

Gotchas and Tips

Pitfalls

1. Filter Precedence Confusion:

   • Programmatic filters override config: A ->filter() call in code takes priority over config/flare.php rules.
   • Callback order matters: Later callbacks in a chain may override earlier ones.

2. Overly Aggressive Filtering:

   • Risk of suppressing critical errors (e.g., catch-all callbacks that return false).
   • Solution: Test filters with APP_DEBUG=true and log skipped reports:

     Flare::report($e)->filter(function (\Exception $e) {
         if (app()->environment('local')) {
             Log::debug("Skipping local report: " . $e->getMessage());
             return false;
         }
         return true;
     });
     

3. Performance in Filter Callbacks:

   • Avoid expensive operations (e.g., DB queries) in filter callbacks.
   • Solution: Cache results or use lightweight checks:

     // Bad: DB query in filter
     ->filter(function (\Exception $e) {
         return DB::table('errors')->where('id', $e->getCode())->exists();
     });
     
     // Good: Pre-compute or use simple logic
     ->filter(function (\Exception $e) {
         return $e->getCode() >= 500;
     });
     

4. Wildcard Filtering Quirks:

   • messages wildcards (*) are case-sensitive and match substrings.
   • Example: '*Timeout*' matches "Request Timeout" but not "timeout error".

5. Filtering and ->later():

   • Filters are applied before queuing. Ensure async reports respect your filtering logic.

6. Type Hierarchy in Filtering:

   • If you exclude \RuntimeException, subclasses (e.g., \InvalidArgumentException) are not automatically excluded unless specified.
   • Solution: Explicitly list all relevant types or use a callback:

     'filter' => [
         'types' => [\RuntimeException::class, \InvalidArgumentException::class],
     ],
     

Debugging

• Verify Filter Rules:

  • Temporarily disable all filters to isolate issues:

    'filter' => false, // Disable in config
    

  • Or log filter results:

    Flare::report($e)->filter(function (\Exception $e) {
        $shouldReport = strpos($e->getMessage(), 'error') !== false;
        Log::debug("Filter result for {$e::class}: " . ($shouldReport ? 'PASS' : 'BLOCK'));
        return $shouldReport;
    });
    

• Check Filter Order:

  • Use ->then() to chain filters and debug precedence:

    Flare::report($e)
         ->filter(function (\Exception $e) { /* First filter */ })
         ->then(function ($payload) { /* Inspect payload */ })
         ->filter(function (\Exception $e) { /* Second filter */ });
    

• Test with Edge Cases:

  • Validate filters with:
    • Nested exceptions ($e->getPrevious()).
    • Non-string messages (e.g., null or objects).
    • Custom exception classes.

Extension Points

1. Custom Filter Logic:

   • Create reusable filter classes:

     class ProductionOnlyFilter
     {
         public function __invoke(\Exception $e)
         {
             return app()->environment('production');
         }
     }
     Flare::report($e)->filter(new ProductionOnlyFilter());
     

2. Filter Validation:

   • Extend the package to validate filter rules at runtime:

     Flare::extend(function ($payload) {
         if (empty($payload['exception']['class'])) {
             throw new \InvalidArgumentException("Invalid exception payload");
         }
         return $payload;
     });
     

3. Filter Presets:

   • Define filter presets in config for different environments:

     'filters' => [
         'production' => [
             'types' => [\RuntimeException::class],
             'messages' => ['*critical*'],
         ],
         'staging' => [
             'callback' => function (\Exception $e) {
                 return true; // Report everything
             },
         ],
     ];
     

4. Filter Events:

   • Listen for filter decisions:

     event(new FlareFiltering($e, $shouldReport));
     

   • Note: Requires extending the package or using a wrapper.

5. Dynamic Filter Loading:

   • Load filters from a database or cache:

     $filterRules = Cache::get('flare_filters');
     Flare::report($e)->filter(function (\Exception $e) use ($filterRules) {
         return $filterRules['callback']($e);
     });
     

Config Quirks

• Filter Syntax Validation:
  • The config schema now validates filter rules. Invalid entries (e.g., non-callable callback) will throw: