Consul Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sensiolabs/consul-php-sdk
   

   Ensure your PHP version (≥8.0) and extensions (curl, json) are compatible.

2. First Connection

   use SensioLabs\Consul\Consul;
   
   $consul = new Consul('http://localhost:8500');
   

   Replace the URL with your Consul server address.

3. First Use Case: Agent Self-Check

   $agent = $consul->getAgent();
   $status = $agent->getSelf();
   dd($status); // Check service health, node details, etc.
   

Where to Look First

• Official Documentation (if available) or the source code for API reference.
• src/SensioLabs/Consul/ directory for core classes (e.g., Consul.php, Agent.php, Catalog.php).
• tests/ folder for real-world usage examples.

Implementation Patterns

Core Workflows

Service Discovery

$catalog = $consul->getCatalog();
$services = $catalog->getServices(); // List all registered services
$service = $catalog->getService('web'); // Fetch a specific service

Key-Value Store

$kv = $consul->getKv();
$kv->set('app/config', json_encode(['debug' => true])); // Store config
$value = $kv->get('app/config')->getValue(); // Retrieve config

Health Checks

$health = $consul->getHealth();
$checks = $health->getChecks(); // List all checks
$serviceChecks = $health->getChecksForService('api'); // Filter by service

Session Management

$session = $consul->getSession();
$session->create('lock-token', 'app-lock', 30); // Create a session (TTL: 30s)
$lock = $session->getLock('lock-token'); // Acquire lock

Integration Tips

1. Dependency Injection (Laravel) Bind the SDK in AppServiceProvider:

   $this->app->singleton(Consul::class, function ($app) {
       return new Consul(config('consul.url'));
   });
   

   Inject via constructor:

   public function __construct(private Consul $consul) {}
   

2. Retry Logic for Transient Failures Use Laravel’s retry helper or a custom decorator:

   $retry = 3;
   while ($retry--) {
       try {
           $services = $consul->getCatalog()->getServices();
           break;
       } catch (\Exception $e) {
           if ($retry === 0) throw $e;
           sleep(1);
       }
   }
   

3. Async Operations with Queues Offload long-running tasks (e.g., bulk KV writes) to queues:

   dispatch(new WriteToConsul($consul, $data))->onQueue('consul');
   

4. Environment-Specific Config Use Laravel’s .env:

   CONSUL_URL=http://consul:8500
   CONSUL_TOKEN=your-token-if-auth-enabled
   

   Load in config/consul.php:

   'url' => env('CONSUL_URL'),
   'token' => env('CONSUL_TOKEN'),
   

Gotchas and Tips

Pitfalls

1. Connection Timeouts

   • Consul’s default timeout (5s) may be too short for slow networks.
   • Fix: Extend timeout in the client:

     $consul = new Consul('http://consul:8500', [
         'timeout' => 10.0, // 10 seconds
     ]);
     

2. Token Authentication

   • If Consul uses ACLs, omit the token to avoid 403 Forbidden:

     $consul = new Consul('http://consul:8500', [
         'token' => env('CONSUL_TOKEN'),
     ]);
     

   • Debugging: Check CONSUL_HTTP_TOKEN env var if using Laravel’s env().

3. Rate Limiting

   • Consul may throttle requests. Implement exponential backoff:

     use Symfony\Component\Process\Exception\TimeoutException;
     
     try {
         $consul->getCatalog()->getServices();
     } catch (TimeoutException $e) {
         sleep(2 ** $attempt++); // Exponential backoff
         retry();
     }
     

4. Stale Data

   • Consul’s cache is eventual. Use ?wait=10s for real-time updates:

     $services = $consul->getCatalog()->getServices(['wait' => '10s']);
     

5. Namespace Collisions

   • Avoid hardcoding keys in KV store. Use namespaced keys:

     $kv->set('app/v1/config', $data); // Prefix with app version
     

Debugging Tips

1. Enable HTTP Logging

   $consul = new Consul('http://consul:8500', [
       'logger' => new \Monolog\Logger('consul', [
           new \Monolog\Handler\StreamHandler(storage_path('logs/consul.log')),
       ]),
   ]);
   

2. Validate API Responses Check for Consul\Exception\ConsulException and inspect raw responses:

   try {
       $consul->getKv()->get('nonexistent-key');
   } catch (ConsulException $e) {
       $response = $e->getResponse();
       dd($response->getStatusCode(), $response->getBody());
   }
   

3. Test Locally with Docker Spin up Consul via Docker:

   docker run -d --name consul -p 8500:8500 consul
   

   Test interactions with curl first:

   curl http://localhost:8500/v1/catalog/services
   

Extension Points

1. Custom HTTP Client Override the default Guzzle client for middleware (e.g., retries, auth):

   $client = new \GuzzleHttp\Client([
       'timeout' => 15,
       'headers' => ['User-Agent' => 'MyApp/1.0'],
   ]);
   $consul = new Consul('http://consul:8500', [], $client);
   

2. Event Listeners Subscribe to Consul events (e.g., service registration changes) via webhooks or polling:

   $events = $consul->getEvents();
   $event = $events->getEvents(['type' => 'service']); // Filter by type
   

3. Decorators for Metrics Wrap the SDK to track request latency:

   class MetricsConsulDecorator implements ConsulInterface {
       public function __construct(private Consul $consul) {}
   
       public function getAgent() {
           $start = microtime(true);
           $agent = $this->consul->getAgent();
           $latency = microtime(true) - $start;
           // Log $latency to Prometheus/StatsD
           return $agent;
       }
   }
   

4. Fallback Mechanisms Implement a fallback to etcd or local cache if Consul is unavailable:

   try {
       $services = $consul->getCatalog()->getServices();
   } catch (\Exception $e) {
       $services = cache()->get('consul_fallback_services', []);
   }