Filament Spatie Laravel Health Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Run composer require shuvroroy/filament-spatie-laravel-health spatie/laravel-health to install both packages. Ensure filament/filament is also installed (composer require filament/filament).

2. Publish Config Publish the package config with:

   php artisan vendor:publish --provider="ShuvroRoy\FilamentSpatieLaravelHealth\FilamentSpatieLaravelHealthServiceProvider" --tag="config"
   

   This generates config/filament-spatie-laravel-health.php.

3. Register Checks Define health checks in config/health.php (from spatie/laravel-health). Example:

   'checks' => [
       \Spatie\Health\Checks\Checks\DatabaseConnection::new(),
       \Spatie\Health\Checks\Checks\CacheConnection::new(),
   ],
   

4. Access the Page The health dashboard will appear under Resources > Health in your Filament admin panel.

First Use Case: Quick System Health Audit

• Navigate to the Health page in Filament.
• Run the default checks (database, cache, queue, etc.) to verify system status.
• Use the "Run All" button to execute all registered checks at once.

Implementation Patterns

Workflow: Integrating Custom Checks

1. Define Checks Extend spatie/laravel-health checks in config/health.php:

   'checks' => [
       \App\Health\Checks\CustomCheck::new(), // Custom class
       \Spatie\Health\Checks\Checks\Storage::new(), // Built-in check
   ],
   

   Example custom check:

   namespace App\Health\Checks;
   use Spatie\Health\Checks\Check;
   
   class CustomCheck extends Check {
       public function run(): array {
           return [
               'status' => 'ok',
               'message' => 'Custom logic passed',
           ];
       }
   }
   

2. Group Checks Use the group() method in config to organize checks:

   'checks' => [
       \Spatie\Health\Checks\Checks\DatabaseConnection::new()->group('Database'),
       \Spatie\Health\Checks\Checks\CacheConnection::new()->group('Cache'),
   ],
   

3. Conditional Checks Skip checks based on environment:

   'checks' => [
       app()->environment('local') ? \Spatie\Health\Checks\Checks\Queue::new() : null,
   ],
   

Integration Tips

• Filament Widgets Embed health status as a widget in your Filament dashboard:

  use ShuvroRoy\FilamentSpatieLaravelHealth\Widgets\HealthStatusWidget;
  
  public function getWidgets(): array {
      return [
          HealthStatusWidget::class,
      ];
  }
  

• Scheduled Runs Use Laravel’s scheduler to run checks periodically:

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

• API Access Expose health checks via API using spatie/laravel-health's HealthCheckRunner:

  use Spatie\Health\HealthCheckRunner;
  
  Route::get('/api/health', function () {
      return HealthCheckRunner::run();
  });
  

Gotchas and Tips

Pitfalls

1. Missing Dependencies

   • Ensure spatie/laravel-health is installed. The package won’t work without it.
   • Verify filament/filament is installed (v2+ recommended).

2. Permission Issues

   • Filament’s health page requires admin access by default. Override in config/filament.php:

     'pages' => [
         'health' => [
             'permission' => 'view-health',
         ],
     ],
     

3. Check Failures in Development

   • Some checks (e.g., QueueConnection) may fail in local environments. Exclude them:

     app()->environment('local') ? null : \Spatie\Health\Checks\Checks\Queue::new(),
     

4. Caching Side Effects

   • Health checks may cache results. Clear cache after config changes:

     php artisan cache:clear
     php artisan view:clear
     

Debugging

• Check Logs Enable debug mode in config/filament-spatie-laravel-health.php:

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

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

• Manual Check Execution Run checks via CLI for debugging:

  php artisan health:run
  

• Verify Config Ensure config/health.php is properly loaded. Test with:

  php artisan health:list
  

Extension Points

1. Customize UI Override the Filament page by publishing views:

   php artisan vendor:publish --provider="ShuvroRoy\FilamentSpatieLaravelHealth\FilamentSpatieLaravelHealthServiceProvider" --tag="views"
   

   Modify resources/views/vendor/filament-spatie-laravel-health/....

2. Add Check Metadata Extend checks with custom metadata (e.g., severity, description):

   \Spatie\Health\Checks\Checks\DatabaseConnection::new()
       ->description('Verifies MySQL connection')
       ->severity('high'),
   

3. Hook into Check Results Listen for check events in EventServiceProvider:

   protected $listen = [
       \Spatie\Health\Events\CheckWasRun::class => [
          \App\Listeners\LogHealthCheck::class,
      ],
   ];
   

4. Localization Translate check messages by publishing lang files:

   php artisan vendor:publish --provider="ShuvroRoy\FilamentSpatieLaravelHealth\FilamentSpatieLaravelHealthServiceProvider" --tag="lang"
   

   Override in resources/lang/{locale}/health.php.