Health Check Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer (assuming Symfony compatibility via Laravel's Symfony bridge or a standalone Symfony app):

   composer require apiboxsym/health-check-bundle
   

   Register the bundle in your config/bundles.php (Symfony) or manually bootstrap it in Laravel via a service provider.

2. Route Registration The bundle auto-registers a /health endpoint. Verify by running:

   php artisan route:list  # (Laravel) or `php bin/console debug:router` (Symfony)
   

   Expected output:

   GET  | /health          | health.check.controller
   

3. First Use Case Test the endpoint locally:

   curl http://localhost:8000/health
   

   Expected response:

   {"status":"ok"}
   

Implementation Patterns

Core Workflows

1. Basic Health Check Use the /health endpoint for:

   • Kubernetes liveness/readiness probes.
   • CI/CD pipeline health validations.
   • External service monitoring (e.g., Prometheus, Datadog).

2. Customizing Responses Extend the default response by overriding the controller:

   // app/Http/Controllers/HealthController.php (Laravel)
   namespace App\Http\Controllers;
   use ApiBoxSym\HealthCheckBundle\Controller\HealthController as BaseHealthController;
   
   class HealthController extends BaseHealthController
   {
       public function check()
       {
           return response()->json([
               'status' => 'ok',
               'version' => '1.0.0',
               'environment' => env('APP_ENV'),
           ]);
       }
   }
   

   Update routes to point to your custom controller.

3. Dependency Checks Integrate with Laravel services (e.g., database, queue) by extending the bundle’s logic:

   // Override the bundle’s service (Symfony)
   services:
       ApiBoxSym\HealthCheckBundle\Service\HealthChecker:
           class: App\Service\CustomHealthChecker
           arguments:
               - '@database.connection'
               - '@queue.worker'
   

4. API Versioning Add versioned health checks (e.g., /health/v1):

   // routes/web.php (Laravel)
   Route::prefix('health')->group(function () {
       Route::get('/v1', [HealthController::class, 'check']);
   });
   

Gotchas and Tips

Pitfalls

1. Namespace Conflicts The bundle assumes a Symfony environment. In Laravel, manually register routes/services to avoid autoloading issues:

   // config/app.php (Laravel)
   'providers' => [
       // ...
       ApiBoxSym\HealthCheckBundle\HealthCheckBundle::class,
   ];
   

2. Caching Headers The default endpoint lacks caching headers. Add them in Laravel:

   return response()->json(['status' => 'ok'])
       ->header('Cache-Control', 'public, max-age=60');
   

3. Testing Edge Cases The bundle lacks built-in error handling. Test failure modes:

   // tests/Feature/HealthCheckTest.php (Laravel)
   public function test_health_check_fails_when_database_down()
   {
       \Mockery::mock('database.connection')->shouldReceive('getPdo')->andThrow(new \PDOException);
       $response = $this->get('/health');
       $response->assertStatus(503);
   }
   

Tips

1. Monitoring Integration Use the endpoint with tools like:

   • Prometheus: Scrape /health with a custom exporter.
   • UptimeRobot: Ping /health for uptime alerts.

2. Custom Status Codes Return 503 for degraded services:

   if (!\DB::connection()->getPdo()) {
       return response()->json(['status' => 'degraded'], 503);
   }
   

3. Documentation Add OpenAPI/Swagger annotations for the endpoint:

   /**
    * @OA\Get(
    *     path="/health",
    *     summary="Health check endpoint",
    *     responses={
    *         200={ "description": "Service is healthy" }
    *     }
    * )
    */
   

4. Extending Checks Add modular checks via events (Symfony) or service providers (Laravel):

   // Laravel Service Provider
   public function register()
   {
       $this->app->singleton('health.checks', function () {
           return collect([
               'database' => fn() => \DB::connection()->getPdo() !== null,
               'cache' => fn() => \Cache::store('file')->get('test') === 'test',
           ]);
       });
   }