Symfony Actuator Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/package-name

Publish the configuration (if needed) and register the service provider in config/app.php under the providers array:

Vendor\PackageName\PackageServiceProvider::class,

The package provides two basic endpoints out of the box:

• Health Check: Access /health for a simple status response (e.g., {"status": "ok"}).
• Info Endpoint: Access /info for package metadata (e.g., version, environment details).

First Use Case: Quickly integrate a /health endpoint for monitoring tools (e.g., Prometheus, UptimeRobot) or API gateways. Example:

// In routes/web.php or routes/api.php
Route::get('/health', [Vendor\PackageName\Http\Controllers\HealthController::class, 'check']);

Implementation Patterns

Core Workflows

1. Health Checks:

   • Extend the default response by overriding the Vendor\PackageName\Http\Controllers\HealthController or binding a custom controller.
   • Example: Add database connectivity checks:

     public function check()
     {
         $status = ['status' => 'ok'];
         if (!$this->database->connection()->getPdo()) {
             $status['database'] = 'unreachable';
         }
         return response()->json($status);
     }
     

   • Register custom checks via the health-checks config array:

     'checks' => [
         'database' => \Vendor\PackageName\Checks\DatabaseCheck::class,
     ],
     

2. Info Endpoint:

   • Customize the payload by extending Vendor\PackageName\Http\Controllers\InfoController or binding a new controller.
   • Example: Add app-specific details:

     public function info()
     {
         return response()->json([
             'version' => '1.0.0',
             'environment' => app()->environment(),
             'custom' => ['feature_flag' => config('app.feature_flag')],
         ]);
     }
     

Integration Tips

• API Gateways: Use the /health endpoint for circuit breakers or load balancers.
• Monitoring: Scrape /info for dynamic metadata in dashboards (e.g., Grafana).
• Middleware: Protect endpoints with throttle or auth middleware if needed:

  Route::middleware(['throttle:60'])->get('/health', [HealthController::class, 'check']);
  

Gotchas and Tips

Pitfalls

1. Endpoint Collisions:

   • Ensure /health and /info routes don’t conflict with existing routes. Use route model binding or middleware to namespace them (e.g., prefix with /api/v1).
   • Example:

     Route::prefix('api/v1')->group(function () {
         Route::get('/health', [HealthController::class, 'check']);
     });
     

2. Performance:

   • Avoid heavy operations in /health (e.g., queries, external API calls). Keep responses lightweight for monitoring tools.
   • Cache the /info response if it includes static data:

     return Cache::remember('package-info', 3600, function () {
         return $this->infoPayload();
     });
     

3. Configuration Overrides:

   • The package uses config/package-name.php for settings. Ensure the config file exists and is published:

     php artisan vendor:publish --tag=package-name-config
     

Debugging

• Endpoint Not Found:

  • Verify the service provider is registered and the routes are published (check bootstrap/app.php or routes/web.php).
  • Run php artisan route:list to confirm the routes exist.

• Custom Checks Failing:

  • Check the health-checks config array for typos or missing dependencies (e.g., database drivers).
  • Enable debug mode (APP_DEBUG=true) to log errors from custom checks.

Extension Points

1. Custom Controllers:

   • Bind your own controllers for full control:

     $this->app->bind(
         Vendor\PackageName\Http\Controllers\HealthController::class,
         App\Http\Controllers\CustomHealthController::class
     );
     

2. Dynamic Responses:

   • Override the Vendor\PackageName\Contracts\HealthCheck interface to create reusable check logic:

     class CustomCheck implements HealthCheck {
         public function check(): array {
             return ['status' => $this->evaluate()];
         }
     }
     

3. Localization:

   • Extend the response language by overriding the lang config or using Laravel’s localization features:

     'responses' => [
         'health' => [
             'ok' => __('package::health.ok'),
         ],
     ],