Bugcatch Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require culabs/bugcatch
   

   Add the service provider to config/app.php under providers:

   Culabs\BugCatch\BugCatchServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Culabs\BugCatch\BugCatchServiceProvider" --tag="config"
   

   Update config/bugcatch.php with your BugCatch API key and project ID.

3. First Use Case Wrap error-prone code in a try-catch block and log errors:

   use Culabs\BugCatch\Facades\BugCatch;
   
   try {
       // Risky operation (e.g., API call, DB query)
       $result = $this->riskyOperation();
   } catch (\Exception $e) {
       BugCatch::logError($e, [
           'user_id' => auth()->id(),
           'context' => 'Payment processing',
       ]);
       throw $e; // Re-throw if needed
   }
   

Implementation Patterns

Error Logging Workflows

1. Automatic Logging Use middleware to log uncaught exceptions globally:

   // app/Http/Middleware/LogErrors.php
   public function handle($request, Closure $next) {
       try {
           return $next($request);
       } catch (\Exception $e) {
           BugCatch::logError($e, ['request' => $request->all()]);
           throw $e;
       }
   }
   

   Register in app/Http/Kernel.php:

   protected $middleware = [
       \App\Http\Middleware\LogErrors::class,
   ];
   

2. Manual Logging Log errors with custom metadata (e.g., user sessions, request data):

   BugCatch::logError($e, [
       'user_agent' => $request->userAgent(),
       'ip' => $request->ip(),
       'route' => $request->route()->getName(),
   ]);
   

3. Logging Exceptions in Artisan Commands

   use Culabs\BugCatch\Facades\BugCatch;
   
   public function handle() {
       try {
           // Command logic
       } catch (\Exception $e) {
           BugCatch::logError($e, ['command' => 'queue:work']);
           throw $e;
       }
   }
   

Integration with Laravel Features

1. Exception Handling Override Laravel’s default exception handler to include BugCatch:

   // app/Exceptions/Handler.php
   public function report(Throwable $exception) {
       BugCatch::logError($exception, [
           'exception' => get_class($exception),
       ]);
       parent::report($exception);
   }
   

2. Queue Failed Jobs Log failures in FailedJob handler:

   // app/Exceptions/Handler.php
   public function handleFailedJob(FailedJob $exception) {
       BugCatch::logError($exception, [
           'job' => get_class($exception->job),
           'attempts' => $exception->attempts(),
       ]);
   }
   

3. Logging HTTP Client Errors Use a wrapper for HTTP clients (e.g., Guzzle):

   $client = new \GuzzleHttp\Client([
       'handler' => \GuzzleHttp\HandlerStack::create([
           new \Culabs\BugCatch\Middleware\LogHttpErrors(),
       ]),
   ]);
   

Gotchas and Tips

Pitfalls

1. Sensitive Data Exposure Avoid logging sensitive data (passwords, tokens) in metadata. Use BugCatch::logError() judiciously:

   // Bad: Logs raw request data
   BugCatch::logError($e, ['request' => $request->all()]);
   
   // Good: Log only non-sensitive data
   BugCatch::logError($e, [
       'method' => $request->method(),
       'path' => $request->path(),
   ]);
   

2. Rate Limits BugCatch may throttle requests. Implement a fallback for critical errors:

   try {
       BugCatch::logError($e);
   } catch (\Exception $fallbackError) {
       // Fallback to file/logger
       \Log::critical($fallbackError->getMessage(), ['exception' => $e]);
   }
   

3. Configuration Overrides Ensure config/bugcatch.php is merged correctly. Test locally with a dummy API key to avoid production issues:

   'api_key' => env('BUGCATCH_API_KEY', 'dummy-key-for-local'),
   

Debugging

1. Verify API Key Check the config file and environment variables:

   php artisan config:clear
   

2. Check Logs Enable Laravel’s debug mode to see if errors are being caught:

   php artisan config:cache
   php artisan route:clear
   

3. Test Locally Use a local BugCatch instance (if available) or mock the client:

   // Mock BugCatch for testing
   $this->partialMock(BugCatch::class, function ($mock) {
       $mock->shouldReceive('logError')->once();
   });
   

Extension Points

1. Custom Metadata Extend the BugCatch facade to add project-specific metadata:

   // app/Providers/BugCatchServiceProvider.php
   public function boot() {
       BugCatch::extend(function ($bugcatch) {
           $bugcatch->setDefaultMetadata([
               'app_version' => '1.0.0',
               'environment' => app()->environment(),
           ]);
       });
   }
   

2. Webhook Integration Use BugCatch’s webhooks to trigger Laravel events or notifications:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'bugcatch.webhook' => [
           \App\Listeners\HandleBugCatchWebhook::class,
       ],
   ];
   

3. Batch Logging For high-volume logging (e.g., CLI scripts), batch errors to reduce API calls:

   $errors = [];
   foreach ($items as $item) {
       try {
           // Process item
       } catch (\Exception $e) {
           $errors[] = [
               'error' => $e,
               'item' => $item,
           ];
       }
   }
   BugCatch::logErrors($errors); // Hypothetical batch method