Vdm Healthcheck Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Microservices/Containerized Deployments: Ideal for Kubernetes/OpenShift environments where liveness/readiness probes are required. Aligns with Kubernetes' healthcheck standards (/healthz conventions).
• Monolithic PHP Apps: Lightweight addition without architectural disruption. Can be integrated alongside existing monitoring (e.g., Blackfire, New Relic).
• Dependency Awareness: Supports external service checks (e.g., databases, APIs) via custom checkers, bridging gaps in Laravel’s native healthchecks.

Integration Feasibility

• Low Coupling: Bundle is self-contained; no forced dependencies beyond Symfony/Laravel core.
• Symfony/Laravel Compatibility: Works with Symfony 5.4+ and Laravel 8+ (via Symfony components). Laravel-specific integration may require adapter layer (e.g., wrapping Symfony’s HttpFoundation).
• Custom Checkers: Extensible via PSR-15 middleware or custom checker classes, enabling integration with Laravel’s service container.

Technical Risk

• Laravel-Specific Gaps:
  • No native Laravel service provider/bootstrapping (Symfony-centric). Risk of route conflicts or middleware misalignment.
  • Laravel’s routing system differs from Symfony’s (routing.yml vs. routes/web.php).
• Secret Handling: Hardcoded secret in config may conflict with Laravel’s .env conventions.
• Checker Implementation: Custom checkers require manual PSR-15 middleware setup or Laravel-specific adapters.
• Testing Overhead: Limited test coverage (1 star, no dependents) suggests unproven reliability in production.

Key Questions

1. Laravel Compatibility:
   • How will Symfony’s routing.yml integrate with Laravel’s routes/web.php?
   • Are there conflicts with Laravel’s built-in healthcheck routes (e.g., /up)?
2. Custom Checkers:
   • What’s the overhead to adapt PSR-15 checkers for Laravel’s service container?
   • Can existing Laravel services (e.g., Database, Cache) be checked without custom code?
3. Secret Management:
   • How to align with Laravel’s .env for secrets (e.g., HEALTHCHECK_SECRET)?
4. Monitoring Integration:
   • Does this bundle support Laravel’s monitoring tools (e.g., Horizon, Laravel Telescope)?
5. Performance:
   • What’s the latency impact of external dependency checks in readiness probes?

Integration Approach

Stack Fit

• Symfony/Laravel Hybrid: Requires minimal adaptation (e.g., wrapping Symfony routes in Laravel’s RouteServiceProvider).
• Kubernetes/Cloud-Native: Directly usable for liveness/readiness probes with minimal config.
• Legacy PHP: Works but may need custom checkers for non-Symfony services (e.g., legacy DB connections).

Migration Path

1. Phase 1: Basic Endpoints

   • Install via Composer.
   • Adapt Symfony routes to Laravel’s routes/web.php:

     Route::get('/liveness', [VdmHealthcheckBundle::class, 'liveness']);
     Route::get('/readiness', [VdmHealthcheckBundle::class, 'readiness']);
     

   • Configure config/packages/vdm_healthcheck.yaml (or .env for secrets).

2. Phase 2: Custom Checkers

   • Implement PSR-15 middleware for Laravel services:

     use Psr\Http\Message\ResponseInterface;
     use Psr\Http\Message\ServerRequestInterface;
     use Psr\Http\Server\MiddlewareInterface;
     
     class DatabaseChecker implements MiddlewareInterface {
         public function process(ServerRequestInterface $request, ResponseInterface $response) {
             // Custom logic (e.g., DB ping)
         }
     }
     

   • Register checkers in config:

     vdm_healthcheck:
       readiness_checkers:
         database: App\Middleware\DatabaseChecker
     

3. Phase 3: Secret Management

   • Override config with .env:

     VDM_HEALTHCHECK_SECRET=my_secret
     

   • Modify bundle’s SecretChecker to read from Laravel’s config.

Compatibility

• Symfony Components: Leverage Laravel’s Symfony bridge (e.g., symfony/http-foundation).
• Laravel-Specific:
  • Replace Symfony’s EventDispatcher with Laravel’s Illuminate\Events\Dispatcher.
  • Adapt HttpFoundation requests/responses to Laravel’s Illuminate\Http.
• External Dependencies: Checkers for non-Symfony services (e.g., Redis, Elasticsearch) may need custom implementations.

Sequencing

1. Pre-Deployment:
   • Test bundle in staging with mock external dependencies.
   • Validate custom checkers in isolation.
2. Deployment:
   • Roll out liveness/readiness endpoints first (minimal risk).
   • Gradually add custom checkers post-deployment.
3. Post-Deployment:
   • Integrate with monitoring tools (e.g., Prometheus, Datadog).
   • Optimize checker performance (e.g., caching, parallel checks).

Operational Impact

Maintenance

• Bundle Updates: Low risk (MIT license, active releases). Monitor for Symfony version compatibility.
• Custom Checkers: High maintenance if tightly coupled to Laravel internals. Document dependencies clearly.
• Secret Rotation: Manual process unless automated via Laravel’s env or a scheduler.

Support

• Limited Community: No dependents or stars may complicate troubleshooting. Prepare for self-support.
• Debugging: Detailed responses require secret access; ensure logging is enabled for unauthenticated errors.
• Laravel-Specific Issues: May need to patch bundle or create a Laravel fork for critical fixes.

Scaling

• Performance:
  • External checks (e.g., DB, APIs) may introduce latency. Use async checks where possible.
  • Cache readiness results if dependencies are stable (e.g., 5-minute TTL).
• Load: Endpoints are stateless; scale horizontally with Laravel’s queue workers for heavy checks.
• Kubernetes: Directly supports probe scaling with minimal overhead.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Document custom checker patterns (e.g., "How to check Laravel’s queue").
  • Provide examples for common services (DB, Redis, third-party APIs).
• Ops Onboarding:
  • Define SLOs for liveness/readiness (e.g., "99.9% of checks must pass").
  • Train teams on secret management and probe configuration.
• Training:
  • Workshop on PSR-15 middleware for developers.
  • Kubernetes-specific training for SREs (probe configuration).