Laravel Health Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Laravel-native: Designed specifically for Laravel, leveraging its service container, facades, and configuration system. Minimal architectural overhead.
  • Modular Checks: Plug-and-play health checks (e.g., disk space, queues, databases, external APIs) align with Laravel’s composable architecture.
  • Extensible: Supports custom checks via inheritance or composition, fitting into Laravel’s event-driven and middleware patterns.
  • Observability-First: Integrates with Laravel’s logging and notification systems (Mail, Slack, etc.), reducing the need for external monitoring tools.
  • Configuration-Driven: Centralized health.php config aligns with Laravel’s convention-over-configuration philosophy.

• Cons:

  • Tight Laravel Coupling: Limited utility outside Laravel ecosystems (e.g., Lumen, non-PHP stacks). Not a concern if the stack is Laravel-exclusive.
  • Middleware Collision Risk: Historical issue with health container alias (fixed in v1.39.2) could resurface in custom middleware-heavy apps.
  • Notification Dependencies: Relies on Laravel’s notification channels (e.g., laravel-notification-channels). May require additional setup for non-standard channels.

Integration Feasibility

• Low-Friction Adoption:
  • Single Composer dependency (spatie/laravel-health) with zero runtime conflicts (MIT license, no hard dependencies beyond Laravel core).
  • Zero database migrations or schema changes (uses Laravel’s built-in caching and logging).
  • Example Integration Time: <30 minutes for basic setup (config + 1–2 checks).
• Key Integration Points:
  • Service Provider: Register checks in AppServiceProvider@boot().
  • Middleware: Optional /health endpoint for HTTP-based monitoring (e.g., Kubernetes probes).
  • Cron Jobs: Schedule checks via Laravel Scheduler (e.g., @hourly).
  • Notifications: Configure in config/health.php (Slack, Mail, etc.).

Technical Risk

• Minimal:
  • Backward Compatibility: Actively maintained (Laravel 10–13 support, 2026-05-28 release). Changelog shows incremental, non-breaking updates.
  • Performance: Checks are lightweight (e.g., disk space, queue size) and designed for async execution. No blocking I/O by default.
  • Security: No direct exposure of sensitive data (configurable via Health::checks()). Middleware collision risk mitigated in v1.39.2+.
• Mitigable Risks:
  • Custom Check Failures: Poorly written checks (e.g., infinite loops) could degrade performance. Mitigate via unit testing and timeout controls (e.g., PingCheck::timeoutMs()).
  • Notification Spam: Default only_on_failure setting (v1.35.0+) reduces noise, but misconfigured thresholds may still flood channels. Use failAfterMinutes to limit alert frequency.

Key Questions for TPM

1. Monitoring Scope:
   • Which checks are critical? (Prioritize checks like DatabaseConnectionCheck, QueueCheck over UsedDiskSpaceCheck.)
   • Do we need custom checks? (E.g., third-party API health, custom business logic.)
2. Notification Strategy:
   • Which channels are supported? (Slack, PagerDuty, custom webhooks?)
   • What’s the escalation policy? (e.g., Slack for warnings, PagerDuty for failures.)
3. Integration with Existing Tools:
   • How will this feed into our observability stack? (e.g., Datadog, Prometheus, custom dashboards.)
   • Will we expose the /health endpoint publicly? (Security review needed if yes.)
4. Operational Ownership:
   • Who will maintain check configurations? (DevOps, SRE, or feature teams?)
   • How will we handle false positives? (e.g., flaky external APIs.)
5. Scaling Considerations:
   • Will checks run in parallel or sequentially? (Affects performance in high-load apps.)
   • How will we handle distributed Laravel deployments? (e.g., multi-AZ, microservices.)

Integration Approach

Stack Fit

• Ideal For:
  • Laravel Monoliths: Single-app deployments with shared state (e.g., queues, databases).
  • Microservices: Per-service health checks with aggregated dashboards (e.g., using the /health endpoint).
  • Serverless/Laravel Vapor: Lightweight, event-driven checks (e.g., queue backlog, external API latency).
• Less Ideal For:
  • Non-Laravel Stacks: Requires significant refactoring for PHP frameworks outside Laravel.
  • Edge/IO-Intensive Checks: Avoid checks that block execution (e.g., full database backups). Use async or external tools instead.

Migration Path

1. Assessment Phase (1–2 weeks):
   • Audit existing monitoring (e.g., New Relic, custom scripts) to identify gaps.
   • Define critical checks (e.g., database, queues, APIs) and non-critical (e.g., disk space).
   • Design notification workflows (e.g., Slack for warnings, PagerDuty for failures).
2. Pilot Phase (1 week):
   • Install in a staging environment.
   • Implement 3–5 core checks (e.g., DatabaseConnectionCheck, QueueCheck, PingCheck).
   • Test notifications and alerting.
3. Rollout Phase (2–4 weeks):
   • Gradually add checks (e.g., CacheCheck, UsedDiskSpaceCheck).
   • Expose /health endpoint with appropriate middleware (e.g., rate limiting, auth).
   • Integrate with existing dashboards (e.g., Grafana, Datadog).
4. Optimization Phase (Ongoing):
   • Tune thresholds (e.g., warnAt: 70%, failAt: 90%).
   • Add custom checks for business-critical logic.
   • Automate check maintenance (e.g., CI/CD updates).

Compatibility

• Laravel Versions: Officially supports 10.x–13.x (tested via CI).
• PHP Versions: Requires PHP 8.1+ (aligned with Laravel 10+).
• Dependencies:
  • Core: None beyond Laravel.
  • Notifications: Requires laravel-notification-channels for Slack/PagerDuty (or custom channels).
  • Databases: Works with all Laravel-supported DBs (MySQL, PostgreSQL, SQLite, etc.).
• Third-Party Conflicts: None reported. MIT license ensures no legal conflicts.

Sequencing

1. Prerequisites:
   • Laravel 10+ application.
   • Notification channels configured (if using Slack/Mail).
   • Basic CI/CD pipeline for testing checks.
2. Order of Operations:
   • Step 1: Install package and publish config (php artisan vendor:publish --provider="Spatie\Health\HealthServiceProvider").
   • Step 2: Register core checks in AppServiceProvider@boot().
   • Step 3: Configure notifications in config/health.php.
   • Step 4: Schedule checks via Laravel Scheduler (app/Console/Kernel.php).
   • Step 5: Expose /health endpoint (optional, via middleware).
   • Step 6: Integrate with monitoring tools (e.g., Prometheus exporter for metrics).

Operational Impact

Maintenance

• Ease of Updates:
  • Minimal: Package updates are backward-compatible (semver-compliant). Example:

    composer update spatie/laravel-health
    

  • Configuration: Centralized in config/health.php (no scattered logic).
• Deprecation Risk:
  • Low. Spatie maintains a clear changelog and deprecation policy (e.g., spatie/temporary-directory moved to require-dev in v1.40.0).
• Custom Checks:
  • Require occasional updates if leveraging Laravel internals (e.g., new queue driver APIs). Test custom checks in CI.

Support

• Troubleshooting:
  • Logs: All check results logged via Laravel’s logging system (configurable in config/health.php).
  • Debugging: Health::checks() returns a Collection of check results with metadata (e.g., isPassing(), message()).
  • Common Issues:
    • False Positives: Tune thresholds or add failAfterMinutes to avoid alert fatigue.
    • Performance: Use async checks (e.g., QueueCheck) or limit check frequency.
• Vendor Support:
  • Community: Active GitHub repo (878 stars, 315+ PRs). Response time for issues: <48 hours.
  • Commercial: Spatie offers paid support via [their products page](https://spatie.be/open-source