Filament Spatie Laravel Health Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Seamless Integration with Filament: Leverages Filament’s plugin system, ensuring native UI/UX consistency with existing admin panels. Reduces friction for developers accustomed to Filament’s workflow.
  • Modular Health Checks: Built on top of spatie/laravel-health, which provides a batteries-included approach with 100+ pre-built checks (e.g., database, queue, cache, environment variables, third-party APIs). Aligns with Laravel’s ecosystem and microservice-friendly design.
  • Extensible: Supports custom checks via Health::checks() and allows UI customization (icons, labels, navigation groups) via Filament’s page extension system.
  • Storage Agnostic: Compatible with multiple result storage backends (database, Redis, etc.), enabling flexibility for different deployment scenarios (e.g., serverless vs. traditional hosting).
  • Observability-First: Provides real-time visibility into system health, critical for DevOps/SRE teams managing Laravel applications.

• Cons:

  • Filament Dependency: Tight coupling with Filament (v3–v5) may limit adoption in projects not using Filament or requiring a standalone health endpoint (e.g., for API consumers).
  • Database Overhead: Eloquent-based storage requires a migration, adding complexity to lightweight deployments (e.g., serverless functions).
  • No Native Alerting: Lacks built-in integrations with monitoring tools (e.g., Datadog, Sentry, PagerDuty). Requires manual setup for alerts.

Integration Feasibility

• Laravel Ecosystem Fit:
  • High: Designed for Laravel (v10–v13) with minimal boilerplate. Complements existing tools like Laravel Horizon, Scout, or Telescope.
  • Filament Compatibility: Tested with Filament v3–v5, ensuring UI consistency. Plugin system reduces merge conflicts.
• Third-Party Dependencies:
  • Spatie Laravel Health: Mature (10K+ downloads), actively maintained, and widely adopted. Minimal risk of breaking changes.
  • Filament: Requires alignment with Filament’s versioning (e.g., v3 vs. v4). Check for breaking changes in Filament’s major releases.
• Customization Surface:
  • High: Supports:
    • Custom health checks (e.g., QueueConnectionCheck, ThirdPartyApiCheck).
    • UI overrides (icons, labels, navigation groups).
    • Authorization logic (e.g., role-based access).
    • Storage backends (e.g., Redis for high-performance environments).

Technical Risk

Key Questions for Stakeholders

1. Observability Goals:
   • Is this for internal DevOps (e.g., monitoring Laravel services) or external consumers (e.g., API health endpoints)?
   • Impact: If external, consider adding a standalone API endpoint (e.g., /health) alongside the Filament UI.
2. Filament Adoption:
   • Is Filament already used in the project, or is this a new integration?
   • Impact: If Filament is new, evaluate the trade-off between UI consistency and standalone health tools (e.g., Laravel’s built-in /up endpoint).
3. Alerting Requirements:
   • Are alerts needed for failed checks (e.g., Slack, PagerDuty)?
   • Impact: If yes, integrate with spatie/laravel-health's webhook support or a third-party tool like Laravel Nova Health.
4. Storage Strategy:
   • Should results be stored in the database, Redis, or another backend?
   • Impact: Database storage adds schema complexity; Redis may require additional infrastructure.
5. Custom Checks:
   • Are there application-specific checks (e.g., payment processor connectivity, custom queue jobs)?
   • Impact: These may require custom Health::check() implementations.
6. Scaling Needs:
   • Will this be used in multi-tenant or microservice architectures?
   • Impact: Consider scoping checks by tenant or service if applicable.

Integration Approach

Stack Fit

• Target Environments:

  • Primary: Laravel (v10–v13) + Filament (v3–v5) applications.
  • Secondary: Standalone Laravel apps (without Filament) could use spatie/laravel-health directly.

• Compatibility Matrix:

  Component	Supported Versions	Notes
  Laravel	10.x–13.x	Tested up to v13 (as of v3.3.0).
  Filament	3.x–5.x	v3.0.0-beta1+ supports Filament v4+.
  PHP	8.1–8.5	PHP 8.5 support added in v3.3.0.
  Spatie Laravel Health	v1.x	Underlying package; stable and mature.
  Database	MySQL, PostgreSQL, SQLite	Eloquent storage requires migrations.
  Storage Backend	Database, Redis, Log File	Configurable via spatie/laravel-health.

• Non-Compatible Scenarios:

  • Laravel < 10: May require polyfills or forks.
  • Filament < 3: Use an older package version (e.g., v2.x).
  • Non-Laravel PHP: Not applicable.

Migration Path

1. Assessment Phase:
   • Audit existing health monitoring (e.g., custom scripts, third-party tools).
   • Identify gaps (e.g., missing checks, no UI, no alerts).
2. Pilot Integration:
   • Step 1: Install the package and basic checks:

     composer require shuvroroy/filament-spatie-laravel-health
     

   • Step 2: Register the plugin in AdminPanelProvider:

     ->plugin(FilamentSpatieLaravelHealthPlugin::make())
     

   • Step 3: Define health checks in AppServiceProvider:

     Health::checks([
         OptimizedAppCheck::new(),
         DatabaseConnectionCheck::new(),
         QueueConnectionCheck::new(),
     ]);
     

   • Step 4: Publish migrations and run:

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

3. Customization Phase:
   • Extend the Filament page for UI/UX tweaks (e.g., icons, labels).
   • Add authorization logic if needed.
   • Implement custom checks for business-critical dependencies.
4. Alerting Integration (Optional):
   • Use spatie/laravel-health's webhook support or integrate with a monitoring tool (e.g., Laravel Nova Health, Sentry).
5. Rollout:
   • Deploy to staging and validate:
     • UI rendering in Filament.
     • Check execution and result storage.
     • Performance impact (e.g., check runtime, database queries).
   • Gradually roll out to production with feature flags if needed.

Compatibility Considerations

• Filament Plugin System:
  • Ensure the PanelProvider is correctly configured to avoid plugin conflicts.
  • Test with Filament’s caching (e.g., filament:cache-reset) if issues arise.
• Health Check Conflicts:
  • Avoid duplicate checks (e.g., both DatabaseConnectionCheck and a custom one).
  • Use Health::check()’s skip() method for conditional checks.
• Storage Backend:
  • If using Redis, ensure the Laravel cache driver is configured.
  • For database storage, verify the health_check_result_history_items table schema matches expectations.

Sequencing

1. Prerequisites:
   • Laravel and Filament installed and configured.
   • Database and storage backends (e.g., Redis) accessible.
2. Core Integration:
   • Install package → Register plugin → Define checks → Run migrations.
3. Customization:
   • UI extensions → Authorization → Custom checks.
4. Validation:
   • Test checks manually → Automate with CI/CD (e.g., GitHub