Oh Dear Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bitbirddev/oh-dear-bundle
   

   Add to config/app.php under providers:

   BitbirdDev\OhDearBundle\OhDearBundle::class,
   

2. Publish Config

   php artisan vendor:publish --provider="BitbirdDev\OhDearBundle\OhDearBundle" --tag="config"
   

   This generates config/oh-dear.php. Configure your Oh Dear API key and project ID.

3. First Use Case: Health Check Create a health check endpoint in routes/web.php:

   use BitbirdDev\OhDearBundle\Http\Controllers\HealthCheckController;
   
   Route::get('/health', [HealthCheckController::class, 'index']);
   

   Visit /health to verify the endpoint works. Oh Dear will now monitor this URL.

Implementation Patterns

Core Workflows

1. Health Check Customization Extend the default health check by creating a custom check class:

   namespace App\Checks;
   
   use BitbirdDev\OhDearBundle\Checks\CheckInterface;
   
   class DatabaseCheck implements CheckInterface
   {
       public function check(): bool
       {
           return DB::connection()->getPdo();
       }
   
       public function description(): string
       {
           return 'Database connection';
       }
   }
   

   Register it in config/oh-dear.php:

   'checks' => [
       \App\Checks\DatabaseCheck::class,
   ],
   

2. Monitoring Multiple Environments Use environment-specific configurations via .env:

   OH_DEAR_PROJECT_ID=prod_123
   OH_DEAR_API_KEY=prod_key
   

   For staging:

   OH_DEAR_PROJECT_ID=staging_456
   OH_DEAR_API_KEY=staging_key
   

3. Integrating with Laravel Scheduler Automate health checks via cron:

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule)
   {
       $schedule->command('oh-dear:check')->hourly();
   }
   

Integration Tips

• Laravel Notifications: Use Oh Dear’s API to trigger notifications when checks fail:

  use BitbirdDev\OhDearBundle\Facades\OhDear;
  
  if (!OhDear::check('database')) {
      Notification::route('mail', 'admin@example.com')
                  ->notify(new HealthCheckFailed('Database'));
  }
  

• Laravel Horizon: Monitor long-running checks with Horizon queues:

  // app/Console/Kernel.php
  $schedule->command('oh-dear:check')->onOneServer()->everyMinute();
  

Gotchas and Tips

Pitfalls

1. API Key Misconfiguration

   • Issue: Oh Dear will silently fail if the API key is invalid.
   • Fix: Validate the key via:

     php artisan oh-dear:validate
     

   • Debug: Check storage/logs/laravel.log for OhDearException.

2. Caching Headaches

   • Issue: Health checks may return stale data if cached.
   • Fix: Disable caching for /health or use Cache::forget() before checks:

     Cache::forget('health_check_cache');
     

3. Environment-Specific Checks

   • Issue: Checks may pass in staging but fail in production due to environment differences.
   • Fix: Use conditional checks:

     public function check(): bool
     {
         return app()->environment('production') ? $this->prodCheck() : true;
     }
     

Debugging

• Enable Verbose Logging Add to config/oh-dear.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs detailed check results to storage/logs/oh-dear.log.

• Manual Check Trigger Run checks manually for testing:

  php artisan oh-dear:check --force
  

Extension Points

1. Custom Check Metrics Extend CheckInterface to return metrics:

   public function metrics(): array
   {
       return [
           'database_latency' => DB::select('SELECT NOW()')[0]->NOW(),
       ];
   }
   

2. Webhook Integration Listen to Oh Dear webhooks for real-time alerts:

   // routes/web.php
   Route::post('/oh-dear/webhook', [OhDearWebhookController::class, 'handle']);
   

3. Slack/Teams Notifications Use Laravel’s via() method in notifications:

   public function via($notifiable)
   {
       return ['SlackMessage'];
   }