Oh Dear App Health Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require devolicious/oh-dear-app-health-bundle

Publish the configuration file to customize thresholds and behavior:

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

The package integrates with Oh Dear to monitor Laravel application health. After configuration, register the service provider in config/app.php under providers:

Devolicious\OhDearBundle\OhDearServiceProvider::class,

The first use case is monitoring uptime and critical errors. Configure your Oh Dear API key in .env:

OH_DEAR_API_KEY=your_api_key_here

Then define health checks in config/oh-dear.php:

'checks' => [
    'uptime' => [
        'enabled' => true,
        'threshold' => 99.9, // New in 1.0.1: Configurable expiration threshold
    ],
    'database' => [
        'enabled' => true,
    ],
],

Run the health check manually:

php artisan oh-dear:check

Implementation Patterns

Workflow Integration

1. Automated Monitoring: Schedule the health check via Laravel's scheduler (app/Console/Kernel.php):

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('oh-dear:check')->everyFiveMinutes();
   }
   

2. Custom Checks: Extend the bundle by creating a custom health check class:

   namespace App\Checks;
   
   use Devolicious\OhDearBundle\Contracts\HealthCheck;
   
   class CustomCheck implements HealthCheck
   {
       public function check(): bool
       {
           // Custom logic
           return true;
       }
   }
   

   Register it in config/oh-dear.php:

   'custom_checks' => [
       App\Checks\CustomCheck::class,
   ],
   

API-Driven Configuration

Use the Oh Dear API to dynamically fetch or update thresholds:

$threshold = config('oh-dear.checks.uptime.threshold');
$response = Http::post('https://api.ohdear.app/thresholds', [
    'threshold' => $threshold,
]);

Gotchas and Tips

Configuration Quirks

• Threshold Overrides: The new threshold setting in 1.0.1 applies to expiration logic (e.g., marking checks as failed if uptime drops below the threshold). Ensure it aligns with Oh Dear's API expectations (default: 99.9).
• Environment-Specific Config: Use Laravel's environment-specific config files (e.g., config/oh-dear-local.php) to override thresholds per environment.

Debugging

• Dry Runs: Test locally without hitting Oh Dear's API by mocking the HTTP client:

  Http::fake([
      'api.ohdear.app/*' => Http::response([], 200),
  ]);
  

• Log Health Checks: Enable logging in config/oh-dear.php:

  'log_checks' => true,
  

  Logs will appear in storage/logs/laravel.log.

Extension Points

• Webhook Handling: Extend the OhDearEventService to handle webhook payloads from Oh Dear:

  namespace App\Listeners;
  
  use Devolicious\OhDearBundle\Events\OhDearWebhookReceived;
  
  class HandleOhDearWebhook
  {
      public function handle(OhDearWebhookReceived $event)
      {
          // Custom logic (e.g., Slack notifications)
      }
  }
  

  Register the listener in EventServiceProvider:

  protected $listen = [
      OhDearWebhookReceived::class => [
          HandleOhDearWebhook::class,
      ],
  ];
  

Pitfalls

• API Rate Limits: Oh Dear's API has rate limits. Avoid excessive checks in development.
• Sensitive Data: Never hardcode API keys in config files. Use Laravel's .env and validate the key exists:

  if (empty(config('services.oh-dear.api_key'))) {
      throw new \RuntimeException('Oh Dear API key not configured.');
  }