Runtime Check Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Laravel Compatibility:

  • The bundle is designed for Symfony (v6.3+ or 7.4+), but Laravel (a PHP framework) can leverage its core logic via standalone components or Symfony bridge packages (e.g., symfony/http-kernel for HTTP checks, symfony/process for CLI/daemon validation).
  • Key Fit: Runtime environment validation (PHP version, extensions, FPM, sockets, etc.) aligns with Laravel’s need for server health monitoring (e.g., deployment checks, CI/CD gates, or runtime assertions).
  • Non-Fit: Symfony-specific features (e.g., symfony/scheduler, security-http) are irrelevant to Laravel but can be abstracted away if only the runtime-check logic is extracted.

• Core Value Proposition:

  • Pre-deployment validation: Verify PHP/FPM/OS config before app boots (e.g., missing ext-posix, misconfigured FPM sockets).
  • Runtime assertions: Fail fast if critical dependencies (e.g., Redis, database) are unavailable.
  • Audit trails: Log checks via Monolog (compatible with Laravel’s logging stack).

Integration Feasibility

• Laravel-Specific Challenges:

  • Service Container: Laravel uses its own DI container (Pimple-based). The bundle’s DependencyInjection extensions would need adaptation (e.g., via Laravel’s ServiceProvider or Package system).
  • Event System: Symfony’s event dispatching (symfony/event-dispatcher) isn’t natively in Laravel, but checks could trigger Laravel’s events or commands.
  • HTTP Layer: The bundle checks FPM errors via FastCGIClient. Laravel’s built-in server (e.g., php artisan serve) wouldn’t need this, but production servers (Nginx/Apache + FPM) would.

• Workarounds:

  • Extract Core Logic: Use the bundle’s check classes (e.g., RuntimeCheck, FpmCheck) as standalone PHP libraries, bypassing Symfony dependencies.
  • Wrapper Package: Create a minimal Laravel package that reimplements the bundle’s checks using Laravel’s native components (e.g., Illuminate\Support\Facades\Process instead of symfony/process).

Technical Risk

Key Questions

1. Scope of Adoption:
   • Will this replace existing Laravel runtime checks (e.g., php artisan optimize, custom health routes) or augment them?
2. Environment Coverage:
   • Should checks run in CI/CD, deployments, or runtime (e.g., via middleware)?
3. Customization Needs:
   • Are default checks (e.g., PHP version, extensions) sufficient, or are project-specific validations (e.g., AWS Lambda, Docker) required?
4. Performance Impact:
   • Will checks run synchronously (blocking boot) or asynchronously (e.g., via Laravel Queues)?
5. Alerting:
   • How should failures be surfaced? (e.g., CLI errors, Slack alerts, health check endpoints)

Integration Approach

Stack Fit

• Laravel Compatibility:

  • ✅ Direct Use: Runtime checks (PHP version, extensions, disk space) are framework-agnostic and can be adapted.
  • ⚠️ Partial Use: FPM/socket checks require Laravel-specific wrappers (e.g., Process facade for CLI commands).
  • ❌ Avoid: Symfony-specific features (e.g., scheduler, security-http).

• Dependency Overlap:

  • Shared: monolog/monolog (Laravel uses it), symfony/process (replaceable with Illuminate\Support\Facades\Process).
  • Unique to Laravel:
    • Use Illuminate\Contracts\Console\Kernel for CLI checks.
    • Use Illuminate\Http\Middleware for HTTP-based validations.

Migration Path

1. Phase 1: Proof of Concept (PoC)

   • Extract core check classes (e.g., RuntimeCheck, ExtensionCheck) into a standalone Laravel package.
   • Replace Symfony dependencies with Laravel equivalents:
     • symfony/process → Process::of()
     • hollodotme/fast-cgi-client → Custom FPM socket checker (if needed).
   • Test in a staging environment with Laravel’s service container.

2. Phase 2: Integration

   • Option A: Use as a composer dependency (if only checks are needed) and call them manually in bootstrap/app.php or a ServiceProvider.
   • Option B: Build a Laravel wrapper package (e.g., laravel-runtime-check) that depends on atoolo/runtime-check-bundle internally but exposes a Laravel-friendly API.
   • Option C: Cherry-pick checks into a custom Laravel package (e.g., vendor/bin/runtime-check).

3. Phase 3: Deployment

   • Add checks to:
     • CI/CD pipelines (e.g., GitHub Actions) via php artisan runtime:check.
     • Deploy hooks (e.g., fail if checks return errors).
     • Health routes (e.g., /runtime-check endpoint).

Compatibility

Sequencing

1. Pre-Boot Checks:
   • Run in bootstrap/app.php before the framework initializes.
   • Example:

     $runtimeCheck = new \Atoolo\RuntimeCheckBundle\RuntimeCheck();
     if (!$runtimeCheck->checkAll()) {
         throw new \RuntimeException('Runtime checks failed!');
     }
     

2. Artisan Command:
   • Create php artisan runtime:check for manual/automated validation.
3. Middleware:
   • Add RuntimeCheckMiddleware to validate requests (e.g., for API health checks).
4. Event Listeners:
   • Trigger checks on Illuminate\Foundation\Bootstrap\RegisteredProviders.

Operational Impact

Maintenance

• Pros:
  • MIT License: No legal barriers.
  • Active Development: Recent updates (PHP 8.4 support, FPM error checks).
  • Standalone Checks: Core logic is reusable even if Symfony integration fails.
• Cons:
  • Symfony Dependency Risk: Future Symfony version bumps may break compatibility.
  • Laravel-Specific Overhead: Wrapper package requires maintenance.
• Mitigation:
  • Pin Symfony dependencies to exact versions in composer.json.
  • Document Laravel-specific deviations in a README.

Support

• Documentation Gaps:
  • Bundle docs assume Symfony. Laravel-specific guides needed for:
    • Service provider setup.
    • Custom check implementation.
    • Troubleshooting container conflicts.
• Community:
  • Low Stars (0): Unproven in production; expect to be the first adopter.
  • Workaround: Engage with upstream (Sitepark) for Laravel use cases.
• Support Plan:
  • Open issues on the GitHub repo for Laravel-specific requests.
  • Maintain a separate GitHub repo for the Laravel wrapper (if built).

Scaling

• Performance:
  • Checks are lightweight (file/process checks, no heavy computations).
  • Bottleneck Risk: FPM socket checks may add latency in high-traffic apps.
    • Solution: Cache results (e.g., Redis) or run asynchronously.
• Distributed Systems:
  • Multi-server: Run checks on each node (e.g., Kubernetes liveness probes).
  • Serverless: Adapt checks for Lambda (e.g., skip FPM, add AWS-specific validations).
• Scaling Strategy: