Statamic Health Laravel Package

Technical Evaluation

Architecture Fit

• Statamic-Centric: The package is tightly coupled with Statamic CMS, leveraging its event system and service container. A TPM must evaluate whether the target system is Statamic-based or if this is a proof-of-concept for broader Laravel health monitoring.
• Modular Design: Health checks are registered via a fluent API (Health::checks()), enabling composable, pluggable monitoring. This aligns well with Laravel’s service provider pattern and dependency injection.
• Extensibility: Supports custom checks (e.g., database connections, third-party APIs), but requires PHP/Laravel familiarity to implement. A TPM should assess whether the team has the bandwidth to extend beyond pre-built checks.

Integration Feasibility

• Low Friction for Statamic: Minimal setup (composer install + service provider binding). Ideal for Statamic-first projects.
• Laravel Compatibility: Works with any Laravel app, but Statamic-specific checks (e.g., cache, entries) may not apply. A TPM must validate if the package’s core checks (disk, DB, queues) suffice or if custom checks are needed.
• Version Lock: Last release in 2022 raises concerns about Statamic v4+ compatibility. A TPM should:
  • Test against the target Statamic/Laravel version.
  • Plan for backward compatibility or fork if critical updates are needed.

Technical Risk

• Stagnation Risk: No recent activity or dependents signal low maintenance. A TPM should:
  • Audit the codebase for technical debt (e.g., outdated Laravel features).
  • Document risks in the architecture decision record (ADR).
• Notification Dependencies: Relies on Statamic’s notification system. If the app uses a custom notification stack, integration may require additional work.
• Performance Overhead: Health checks run on demand (e.g., /health endpoint). A TPM should:
  • Benchmark impact on cold starts or high-traffic routes.
  • Consider caching results if checks are resource-intensive.

Key Questions

1. Is Statamic the primary CMS? If not, does the package’s Laravel-agnostic checks (e.g., disk, DB) meet requirements?
2. What’s the upgrade path? Will Statamic v4+ break compatibility? Is a fork justified?
3. Who owns notifications? Does the app use Statamic’s default notifications, or will custom logic be needed?
4. How will checks be triggered? Endpoint-only, cron jobs, or real-time monitoring?
5. What’s the SLA for health alerts? Are there false-positive risks (e.g., disk space spikes)?

Integration Approach

Stack Fit

• Laravel/Statamic: Native fit. Leverage existing service providers and facades for minimal boilerplate.
• Non-Statamic Laravel: Useful for core checks (DB, queues, cache) but requires custom Statamic-specific checks to be built.
• Non-Laravel PHP: Not recommended—relies on Laravel’s container and events.

Migration Path

1. Assessment Phase:
   • Inventory existing monitoring (e.g., New Relic, Sentry, custom scripts).
   • Map gaps (e.g., "No disk space alerts" → UsedDiskSpaceCheck).
2. Pilot Phase:
   • Install via Composer: composer require spatie/statamic-health.
   • Register checks in AppServiceProvider (or a dedicated HealthServiceProvider).
   • Test the /health endpoint locally.
3. Rollout Phase:
   • Integrate with alerting systems (e.g., Slack, PagerDuty) via Statamic notifications.
   • Document check thresholds (e.g., "Warn at 70% disk usage").
4. Customization Phase (if needed):
   • Extend with custom checks (e.g., StatamicEntriesCheck).
   • Override notification channels if not using Statamic’s defaults.

Compatibility

• Statamic v3.x: Confirmed support (last release).
• Statamic v4.x: Unverified. A TPM should:
  • Test against the target version.
  • Check for breaking changes in Statamic’s event system or service container.
• Laravel 10+: May need adapters for newer features (e.g., spatie/laravel-health as a fallback).

Sequencing

Operational Impact

Maintenance

• Low Effort for Basic Use: Pre-built checks require no maintenance.
• High Effort for Custom Checks: Custom logic may need updates if Statamic/Laravel evolves.
• Dependency Risk: Relying on an unmaintained package could lead to:
  • Security vulnerabilities (MIT license mitigates this, but no updates = no fixes).
  • Compatibility breaks with Statamic upgrades.

Support

• Limited Community: No dependents or active issues suggest self-support is required.
• Debugging: Errors may surface in:
  • Check logic (e.g., false positives in disk space).
  • Notification delivery (Statamic-specific).
• Workaround Plan: If the package fails, consider:
  • Forking and maintaining it internally.
  • Replacing with spatie/laravel-health + custom Statamic checks.

Scaling

• Performance: Checks are lightweight for most use cases, but:
  • Database-heavy checks (e.g., query performance) could slow down /health.
  • Solution: Cache results or run checks asynchronously (e.g., via Laravel queues).
• Alert Volume: High-threshold checks (e.g., 90% disk) may flood notifications.
  • Mitigation: Implement escalation policies (e.g., only alert on sustained failures).

Failure Modes

Ramp-Up

• For Developers:
  • 1–2 hours to install and configure basic checks.
  • 4–8 hours to customize or debug issues.
• For Ops/DevOps:
  • 2–4 hours to integrate with alerting systems.
  • 1 hour to document thresholds and runbooks.
• Blockers:
  • Lack of Statamic v4+ testing may require additional time.
  • Custom checks require deep Laravel/Statamic knowledge.