Vdm Healthcheck Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require 3slab/vdm-healthcheck-bundle
   

2. Enable Routing: Add to config/routes.yaml (or routing.yml in older Laravel versions):

   vdm_healthcheck:
     resource: "@VdmHealthcheckBundle/Resources/config/routing.yml"
     prefix: /
   

3. First Use Case: Immediately test the default endpoints:
   • /liveness (returns 200 OK if the app is running).
   • /readiness (returns 200 OK if the app is ready to serve traffic).

First Custom Checker

Add a simple database connectivity check in config/packages/vdm_healthcheck.yaml:

vdm_healthcheck:
  readiness_checkers:
    database:
      class: "Vdm\HealthcheckBundle\Checker\DatabaseChecker"
      options:
        dsn: "%env(DATABASE_URL)%"

Implementation Patterns

Core Workflows

1. Liveness vs. Readiness:

   • Use liveness (/liveness) for Kubernetes-style "is the container alive?" checks.
   • Use readiness (/readiness) for "is the app ready to handle requests?" checks (e.g., DB connections, cache, queues).

2. Secret-Protected Details: Configure a secret in vdm_healthcheck.secret (e.g., my_secure_secret). Append ?secret=my_secure_secret to endpoints to get JSON details:

   {
     "status": "healthy",
     "checks": {
       "database": { "status": "ok", "message": "Connection successful" }
     }
   }
   

3. Custom Checkers: Extend Vdm\HealthcheckBundle\Checker\AbstractChecker to create domain-specific checks (e.g., API gateways, external services):

   namespace App\Healthcheck;
   
   use Vdm\HealthcheckBundle\Checker\AbstractChecker;
   
   class ExternalApiChecker extends AbstractChecker
   {
       public function check(): bool
       {
           $response = Http::get('https://api.example.com/health');
           return $response->successful();
       }
   }
   

   Register in config:

   readiness_checkers:
     external_api:
       class: "App\Healthcheck\ExternalApiChecker"
   

Integration Tips

1. Laravel-Specific:

   • Use Laravel’s config() helper to access bundle config:

     $secret = config('vdm_healthcheck.secret');
     

   • Leverage Laravel’s Http client for external checks (injected via constructor).

2. Kubernetes/Orchestration:

   • Deploy with annotations for liveness/readiness probes:

     livenessProbe:
       httpGet:
         path: /liveness
         port: 80
     readinessProbe:
       httpGet:
         path: /readiness?secret=${SECRET}
         port: 80
     

3. Monitoring:

   • Expose /readiness to Prometheus or similar tools by adding a ?format=prometheus query param (extend the bundle or wrap the endpoint).

Gotchas and Tips

Pitfalls

1. Secret Handling:

   • Gotcha: Forgetting to set vdm_healthcheck.secret means all checks return 200 OK without details.
   • Fix: Always configure a secret for production environments.

2. Checker Failures:

   • Gotcha: A failing checker returns 503 Service Unavailable by default. Override this in your custom checker:

     public function getStatusCode(): int
     {
         return 429; // Custom status for rate-limiting checks
     }
     

3. Caching:

   • Gotcha: Readiness checks may cache results if not designed to be idempotent (e.g., queue checks).
   • Fix: Use ->check() logic that’s stateless or resets state per invocation.

Debugging

1. Log Checker Outputs: Enable debug mode in config/packages/vdm_healthcheck.yaml:

   debug: true
   

   Logs will appear in Laravel’s log channel.

2. Test Locally: Simulate failures by mocking dependencies (e.g., use Laravel’s Mockery or Http::fake()):

   Http::fake([
       'https://api.example.com/health' => Http::response('500', 500),
   ]);
   

Extension Points

1. Custom Response Formats: Override the Vdm\HealthcheckBundle\Response\HealthcheckResponseFactory to return JSON, XML, or custom formats:

   namespace App\Healthcheck;
   
   use Vdm\HealthcheckBundle\Response\HealthcheckResponseFactory;
   
   class CustomResponseFactory extends HealthcheckResponseFactory
   {
       public function create(array $checks, bool $isHealthy): string
       {
           return json_encode(['status' => $isHealthy ? 'ok' : 'fail', 'checks' => $checks]);
       }
   }
   

   Bind it in config/services.yaml:

   services:
       Vdm\HealthcheckBundle\Response\HealthcheckResponseFactory: '@App\Healthcheck\CustomResponseFactory'
   

2. Dynamic Checkers: Load checkers dynamically via service providers or container extensions:

   public function register()
   {
       $this->app->extend(
           'vdm_healthcheck.checkers',
           fn ($checkers) => array_merge($checkers, [
               new App\Healthcheck\DynamicChecker(),
           ])
       );
   }
   

3. Rate Limiting: Protect healthcheck endpoints with Laravel’s middleware (e.g., throttle):

   # config/routes.yaml
   vdm_healthcheck:
     resource: "@VdmHealthcheckBundle/Resources/config/routing.yml"
     prefix: /
     middleware: ['throttle:10,1']