Sanitycheck Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Laravel Compatibility: The package is a Symfony bundle, not a Laravel package, meaning it is designed for Symfony’s ecosystem (Dependency Injection, Event Dispatcher, Console components). Laravel’s service container and architecture differ significantly, requiring adaptation or wrapper layers to integrate.
• Use Case Alignment: The core functionality (runtime checks for disk space, permissions, remote systems, etc.) aligns well with Laravel’s need for pre-deployment, cron-based, or real-time health checks. However, Laravel’s built-in tools (e.g., Artisan commands, Service Providers, Facades) may obviate some use cases.
• Extensibility: The package’s modular check definitions (e.g., DiskSpaceCheck, HttpAvailabilityCheck) are reusable but may need Laravel-specific implementations (e.g., using Laravel’s Filesystem, HttpClient, or Process components).

Integration Feasibility

• Symfony vs. Laravel Abstraction: Laravel lacks Symfony’s Bundle system, so integration would require:
  • Option 1: Reimplementing checks as Laravel Service Providers or Console Commands.
  • Option 2: Creating a wrapper package that translates Symfony’s DI/Events to Laravel’s container.
  • Option 3: Using Laravel’s existing tools (e.g., php artisan check:health) to replicate functionality.
• Dependency Conflicts: The bundle relies on Symfony’s HttpKernel, Console, and DependencyInjection components. Laravel’s equivalents (e.g., Illuminate\Console, Illuminate\Contracts\Container) would need mapping or shims.
• Event-Driven Checks: Symfony’s EventDispatcher is tightly coupled. Laravel’s Events or Listeners could replace this, but custom logic would be needed for check scheduling (e.g., via Laravel’s scheduler or queue workers).

Technical Risk

• High Reimplementation Risk: Direct use is not feasible without significant refactoring. A proof-of-concept (PoC) would be critical to validate effort.
• Maintenance Overhead: If wrapped, the package would require dual maintenance (upstream Symfony bundle + Laravel adaptations).
• Performance Impact: Heavy checks (e.g., remote system probes) could bloat Laravel’s bootstrapping if not lazy-loaded (e.g., via booted() in Service Providers).
• Testing Complexity: Checks involving external systems (e.g., databases, APIs) would need mocking in Laravel’s testing framework (Pest/PHPUnit).

Key Questions

1. Why Not Use Laravel’s Native Tools?
   • Does this bundle offer unique checks (e.g., Symfony-specific configs) not covered by Laravel’s Artisan or Horizon?
   • Are there Symfony-specific integrations (e.g., Doctrine DB checks) that Laravel lacks?
2. Integration Scope
   • Should this be a drop-in replacement for existing health checks (e.g., laravel-health)?
   • Or a complementary layer for pre-deployment validation (e.g., in deploy.php)?
3. Execution Model
   • Should checks run on-demand (e.g., via CLI), cron-triggered, or real-time (e.g., middleware)?
4. Error Handling
   • How should failures be surfaced? (e.g., Laravel’s Notification system, Slack alerts, or UI dashboards?)
5. Long-Term Viability
   • Is the upstream Symfony bundle actively maintained? If not, would a Laravel fork be justified?

Integration Approach

Stack Fit

• Laravel Compatibility: Low (Symfony-first design). Integration would require:
  • Service Provider: Replace Symfony’s Bundle with a Laravel ServiceProvider registering checks as singletons.
  • Console Commands: Convert Symfony’s Command classes to Laravel’s Artisan commands (e.g., php artisan sanity:check).
  • Event System: Replace EventDispatcher with Laravel’s Events (e.g., CheckFailed event).
  • Dependency Injection: Use Laravel’s bind() or make() to resolve check dependencies (e.g., Filesystem, HttpClient).
• Alternative Stacks:
  • Symfony Users: This bundle is a native fit with zero changes.
  • Other PHP Frameworks: Could be adapted via PSR-11 containers (e.g., PHP-DI) but would still need event/console abstractions.

Migration Path

1. Assessment Phase:
   • Audit existing Laravel health checks (e.g., laravel-debugbar, spatie/health).
   • Identify gap checks (e.g., Symfony-specific configs, custom validation rules).
2. PoC Phase:
   • Implement 1–2 critical checks (e.g., disk space, DB connectivity) as Laravel Service Providers.
   • Test integration with Laravel’s Artisan and scheduler.
3. Full Integration:
   • Option A: Fork the bundle and rewrite for Laravel (high effort, long-term maintenance).
   • Option B: Build a wrapper package (e.g., laravel-sanitycheck) that adapts the core logic.
   • Option C: Replace with Laravel-native alternatives (e.g., spatie/laravel-health) if functionality overlaps.

Compatibility

• Symfony-Specific Features:
  • Doctrine Checks: Requires Laravel’s Database facade or Eloquent integration.
  • Kernel Events: Replace with Laravel’s Events or Observers.
  • Console Styling: Symfony’s Style interface → Laravel’s Output or custom helpers.
• Laravel-Specific Features:
  • Queue Workers: Checks could be dispatched to Laravel Queues for async execution.
  • Notifications: Failures could trigger Notifiable models (e.g., User::notify(new CheckFailed)).
  • Horizon: For monitoring long-running checks (e.g., remote API probes).

Sequencing

Operational Impact

Maintenance

• Upstream Dependencies:
  • If using the original bundle, Symfony updates may break Laravel compatibility.
  • Solution: Pin versions strictly or fork the bundle.
• Laravel-Specific Bugs:
  • Checks relying on Symfony’s HttpKernel may fail in Laravel’s context (e.g., missing Request stack).
  • Mitigation: Abstract HTTP checks to use Laravel’s HttpClient or Illuminate\Http.
• Documentation:
  • Original docs assume Symfony. Laravel-specific guides (e.g., "Running Checks in Laravel") would be needed.

Support

• Community:
  • Low-starred repo (2 stars) suggests limited community support. Issues may go unanswered.
  • Workaround: Engage with Symfony bundle maintainers or build internal docs.
• Debugging:
  • Symfony’s Debug component may not translate cleanly. Laravel’s Debugbar or Telescope could help.
• Vendor Lock-in:
  • Custom check logic may become tied to the bundle’s structure, making migration harder later.

Scaling

• Performance:
  • Disk/CPU-heavy checks (e.g., scanning large directories) could slow Laravel’s boot time.
  • Mitigation: Lazy-load checks (e.g., only run php artisan sanity:check manually).
• Distributed Systems:
  • Checks for remote systems (e.g., "Is AWS S3 available?") may need caching (e.g., Redis) to avoid redundant calls.
• Horizontal Scaling:
  • If checks run in queue workers, ensure they’re idempotent (e.g., no duplicate alerts).

Failure Modes