Filament Spatie Laravel Health Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require shuvroroy/filament-spatie-laravel-health
   

2. Publish migrations (if using Eloquent storage):

   php artisan vendor:publish --tag="health-migrations"
   php artisan migrate
   

3. Register the plugin in AdminPanelProvider:

   public function panel(Panel $panel): Panel {
       return $panel
           ->plugin(FilamentSpatieLaravelHealthPlugin::make());
   }
   

4. Define health checks in AppServiceProvider:

   public function boot(): void {
       Health::checks([
           OptimizedAppCheck::new(),
           DebugModeCheck::new(),
           EnvironmentCheck::new(),
       ]);
   }
   

5. Run Filament assets:

   php artisan filament:assets
   

First Use Case

Access the Health Check Results page in Filament to monitor:

• Application status (pass/fail/skipped)
• Check durations
• Historical trends (if using database storage)

Implementation Patterns

Core Workflow

1. Register Checks: Use Spatie’s built-in checks (e.g., DatabaseCheck, CacheCheck) or create custom ones.

   Health::checks([
       DatabaseCheck::new()
           ->expectTablesToExist(['users', 'posts'])
           ->expectTablesToBeReadable(['users']),
       CustomCheck::new()->run(function () {
           return Cache::get('critical_key') !== null;
       }),
   ]);
   

2. Customize the Filament Page: Extend the default page for branding/navigation:

   class CustomHealthPage extends BaseHealthCheckResults {
       protected static ?string $navigationIcon = 'heroicon-o-heart';
       public function getHeading(): string {
           return 'System Vitality';
       }
   }
   

   Register it in AdminPanelProvider:

   ->plugin(FilamentSpatieLaravelHealthPlugin::make()
       ->usingPage(CustomHealthPage::class)
   )
   

3. Access Control: Restrict access via the authorize method:

   ->plugin(FilamentSpatieLaravelHealthPlugin::make()
       ->authorize(fn () => auth()->user()->isAdmin())
   )
   

Integration Tips

• Scheduled Checks: Use Laravel’s schedule to run checks periodically:

  $schedule->command('health:check')->daily();
  

• Alerting: Integrate with tools like Slack or PagerDuty by hooking into Spatie’s Health::checks() and adding webhook logic.
• Custom Storage: For non-database storage (e.g., Redis), configure Spatie’s Health::store() before registering checks.

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If using Eloquent storage, ensure the health_check_result_history_items table exists. Run php artisan migrate after publishing migrations.
   • Fix: Manually create the table if migrations fail:

     php artisan vendor:publish --tag="health-migrations" --force
     

2. Check Registration Timing:

   • Health checks must be registered before the first request that triggers them. Place them in AppServiceProvider@boot or a dedicated service provider.
   • Debug Tip: Use Health::checks([])->assertRegistered() to verify checks are loaded.

3. Filament Asset Caching:

   • After updating the package, clear Filament’s assets:

     php artisan filament:assets
     php artisan cache:clear
     

4. Permission Denied:

   • If the page loads blank, check the authorize callback or Filament’s user permissions.

Debugging

• Check Logs: Enable Spatie’s debug mode:

  Health::debug();
  

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

• Manual Check Execution: Run checks manually via Tinker:

  php artisan tinker
  >>> \Spatie\Health\Facades\Health::performChecks();
  

Extension Points

1. Custom Check Status Icons: Override the getStatusIcon method in your extended page class:

   public function getStatusIcon(string $status): string {
       return match ($status) {
           'passed' => 'heroicon-o-check-circle',
           'failed' => 'heroicon-o-x-circle',
           default => 'heroicon-o-minus-circle',
       };
   }
   

2. Dynamic Check Groups: Use getNavigationGroup to categorize checks dynamically:

   public static function getNavigationGroup(): ?string {
       return request()->user()?->isSuperAdmin() ? 'Admin' : 'User';
   }
   

3. Localization: Publish translations:

   php artisan vendor:publish --tag="filament-spatie-laravel-health-translations"
   

   Then customize resources/lang/vendor/filament-spatie-laravel-health/health.php.

Performance

• Disable Unused Checks: Remove checks from Health::checks() if they’re irrelevant (e.g., DebugModeCheck in production).
• Batch Storage: For high-frequency checks, use Health::store(NullHealthResultStore::class) to avoid database bloat.