Laravel Dashboard Oh Dear Uptime Tile Laravel Package

Getting Started

Minimal Setup

1. Installation Require the package via Composer:

   composer require spatie/laravel-dashboard-oh-dear-uptime-tile
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Spatie\Dashboard\DashboardServiceProvider" --tag="dashboard-config"
   

2. Configuration Ensure your config/dashboard.php includes the tile in the tiles array:

   'tiles' => [
       // ...
       \Spatie\Dashboard\Tiles\OhDearUptimeTile::class,
   ],
   

3. Oh Dear API Setup

   • Register your Oh Dear API token in .env:

     OH_DEAR_API_TOKEN=your_api_token_here
     

   • Configure the API URL in config/dashboard.php (if not using Oh Dear’s default):

     'oh_dear' => [
         'api_url' => env('OH_DEAR_API_URL', 'https://api.ohdear.app/v1'),
     ],
     

4. First Use Case Visit your Laravel Dashboard (/dashboard). The tile will automatically fetch and display down sites from Oh Dear, with:

   • A count of down sites.
   • A list of affected URLs (if any).
   • A "View on Oh Dear" link for quick navigation.

Implementation Patterns

Workflows

1. Integration with Laravel Dashboard

   • The tile extends \Spatie\Dashboard\Tile, so it follows the same rendering lifecycle as other dashboard tiles.
   • Customize appearance via Blade templates (published with php artisan vendor:publish --tag=dashboard-views).

2. Data Fetching

   • The tile uses Guzzle to fetch data from Oh Dear’s API. Override the getData() method in a custom tile class to modify the request:

     use Spatie\Dashboard\Tiles\OhDearUptimeTile;
     
     class CustomOhDearTile extends OhDearUptimeTile {
         public function getData()
         {
             $response = $this->http->get('https://api.ohdear.app/v1/sites', [
                 'headers' => [
                     'Authorization' => 'Bearer ' . config('services.oh_dear.token'),
                     'Accept' => 'application/json',
                 ],
             ]);
     
             return $response->json();
         }
     }
     

3. Conditional Rendering

   • Hide the tile when no sites are down by overriding shouldBeDisplayed():

     public function shouldBeDisplayed(): bool
     {
         $data = $this->getData();
         return $data['down'] > 0;
     }
     

4. Real-Time Updates

   • Cache the API response for performance (e.g., 5 minutes):

     use Illuminate\Support\Facades\Cache;
     
     public function getData()
     {
         return Cache::remember('oh_dear_sites', now()->addMinutes(5), function () {
             return $this->http->get('...')->json();
         });
     }
     

5. Multi-Tenant Support

   • Filter sites by tenant ID (if using a multi-tenant setup):

     public function getData()
     {
         $tenantId = auth()->user()->tenant_id;
         return $this->http->get('...', [
             'query' => ['tenant_id' => $tenantId],
         ])->json();
     }
     

Gotchas and Tips

Pitfalls

1. API Rate Limiting

   • Oh Dear’s API may throttle requests. Implement exponential backoff in getData() if you encounter 429 errors:

     try {
         return $this->http->get('...')->json();
     } catch (\GuzzleHttp\Exception\RequestException $e) {
         if ($e->getCode() === 429) {
             sleep(2); // Retry after 2 seconds
             return $this->http->get('...')->json();
         }
         throw $e;
     }
     

2. Token Security

   • Never hardcode API tokens in your tile class. Always use .env or Laravel’s config/services.php:

     OH_DEAR_API_TOKEN=your_token_here
     

     // config/services.php
     'oh_dear' => [
         'token' => env('OH_DEAR_API_TOKEN'),
     ],
     

3. Data Parsing Issues

   • Oh Dear’s API response structure may change. Validate the response in getData():

     $data = $this->http->get('...')->json();
     if (!isset($data['sites'])) {
         throw new \RuntimeException('Invalid API response format');
     }
     

4. Caching Stale Data

   • Avoid caching during development. Use Cache::forget('oh_dear_sites') in routes/web.php for testing:

     Route::get('/clear-oh-dear-cache', function () {
         Cache::forget('oh_dear_sites');
         return 'Cache cleared!';
     });
     

Tips

1. Custom Styling

   • Override the tile’s Blade template (resources/views/vendor/dashboard/tiles/oh-dear.blade.php) to change colors or layout:

     @if($tile->data['down'] > 0)
         <div class="bg-red-100 border border-red-400 text-red-800">
             <!-- Custom content -->
         </div>
     @endif
     

2. Notifications Integration

   • Trigger Laravel notifications when sites go down:

     use Illuminate\Notifications\Notification;
     
     public function shouldBeDisplayed(): bool
     {
         $data = $this->getData();
         if ($data['down'] > 0 && $this->lastChecked['down'] === 0) {
             Notification::send(auth()->user(), new SiteDownNotification($data));
         }
         $this->lastChecked = $data;
         return $data['down'] > 0;
     }
     

3. Environment-Specific Config

   • Use different API tokens for staging/production:

     OH_DEAR_API_TOKEN_STAGING=...
     OH_DEAR_API_TOKEN_PROD=...
     

     // config/dashboard.php
     'oh_dear' => [
         'token' => env('OH_DEAR_API_TOKEN_' . app()->environment()),
     ],
     

4. Testing

   • Mock the HTTP client in tests to avoid real API calls:

     $this->app->instance(\GuzzleHttp\Client::class, \Mockery::mock(\GuzzleHttp\Client::class));
     $mock = $this->app->make(\GuzzleHttp\Client::class);
     $mock->shouldReceive('get')
          ->once()
          ->andReturn((new \GuzzleHttp\Psr7\Response(200, [], json_encode(['down' => 1]))));
     

5. Performance Optimization

   • Lazy-load the tile data only when the tile is visible:

     public function shouldBeDisplayed(): bool
     {
         return true; // Always show the tile
     }
     
     public function render()
     {
         $data = $this->getData(); // Load data only when rendering
         return view('...', ['data' => $data]);
     }