Healthcheck Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require browncat/healthcheck-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Browncat\HealthCheckBundle\HealthCheckBundle::class => ['all' => true],
   ];
   

2. Enable Endpoints: Add to config/routes.yaml:

   health:
     resource: "@HealthCheckBundle/Resources/config/routes.xml"
   

   Clear cache:

   php bin/console cache:clear
   

3. First Use Case: Test the /healthz endpoint to verify basic functionality:

   curl http://localhost/healthz
   

   Expected response: JSON with all registered checks (initially empty).

Implementation Patterns

Core Workflow

1. Define Checks: Create custom checks by implementing Browncat\HealthCheckBundle\Checker\CheckInterface:

   namespace App\HealthCheck;
   
   use Browncat\HealthCheckBundle\Checker\CheckInterface;
   use Browncat\HealthCheckBundle\Checker\Result;
   
   class DatabaseCheck implements CheckInterface
   {
       public function check(): Result
       {
           // Logic to test DB connection
           return new Result(true, "Database is reachable");
       }
   }
   

2. Register Checks: Configure checks in config/packages/health_check.yaml:

   browncat_healthcheck:
       checks:
           database:
               class: App\HealthCheck\DatabaseCheck
               tags: [readiness]  # or [liveness, startup]
   

3. Endpoint Integration:

   • /healthz: Returns JSON with all checks (status + message).
   • /health/readiness: Returns 503 if any readiness check fails (Kubernetes-friendly).
   • /health/liveness: Returns 503 if any liveness check fails (Kubernetes-friendly).

4. Tag-Based Routing: Use tags (readiness, liveness, startup) to group checks for specific endpoints. Example:

   checks:
       cache:
           class: App\HealthCheck\CacheCheck
           tags: [readiness, startup]
   

Advanced Patterns

• Dependency Injection: Inject services into checks via constructor:

  public function __construct(private Connection $db)
  {
  }
  

  Register the service in config/services.yaml:

  services:
      App\HealthCheck\DatabaseCheck:
          arguments:
              $db: '@database_connection'
  

• Dynamic Checks: Load checks dynamically via a compiler pass or runtime configuration.

• Custom Endpoints: Extend the bundle by creating a custom checker (e.g., CustomChecker) and binding it to a route.

Gotchas and Tips

Common Pitfalls

1. Cache Clearing: Forgetting to run php bin/console cache:clear after adding checks or routes will result in silent failures.

2. Tag Mismatches: Checks tagged for /health/readiness won’t appear in /health/liveness responses. Verify tags in health_check.yaml.

3. Result Codes: The bundle returns 503 for failures, but Kubernetes expects 200 with a body for readiness/liveness. Ensure your orchestration tool handles this (e.g., curl -f or status code checks).

4. Startup Checks: StartupChecker runs once at boot. Use sparingly for critical initialization tasks (e.g., DB migrations).

Debugging Tips

• Check Logs: Enable debug mode (APP_ENV=dev) to log check execution:

  browncat_healthcheck:
      debug: true
  

• Validate Config: Use php bin/console debug:container to verify checks are registered:

  php bin/console debug:container | grep HealthCheck
  

• Test Locally: Simulate failures in checks to test endpoint responses:

  return new Result(false, "Simulated failure");
  

Extension Points

1. Custom Checkers: Extend Browncat\HealthCheckBundle\Checker\CheckerInterface to create custom logic (e.g., periodic checks).

2. Response Format: Override the JSON response by binding a custom ResponseFactory:

   browncat_healthcheck:
       response_factory: App\HealthCheck\CustomResponseFactory
   

3. HTTP Status Codes: Modify failure responses by implementing Browncat\HealthCheckBundle\Checker\ResponseFactoryInterface.

4. Integration with Monitoring: Use the /healthz JSON output to feed metrics to tools like Prometheus or Datadog. Example:

   // In a custom checker
   $this->monitoringClient->recordCheck($result);