Open Api Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require docker-client/open-api
   

   Ensure your composer.json targets PHP 7.4+ (check supported versions).

2. First Use Case: Initialize the client and list containers:

   use Docker\Client;
   
   $client = new Client();
   $containers = $client->containers()->listContainers();
   print_r($containers);
   

3. Where to Look First:

   • Generated API Docs (auto-generated from OpenAPI spec).
   • Docker Engine API v1.40 for endpoint details.
   • src/Api/ directory in the package for raw API classes (if extending).

Implementation Patterns

Core Workflows

1. Basic CRUD Operations:

   // Create a container
   $client->containers()->createContainer([
       'Image' => 'nginx:latest',
       'Cmd' => ['nginx', '-g', 'daemon off;'],
   ]);
   
   // Start/Stop
   $client->containers()->start('container_id');
   $client->containers()->stop('container_id');
   
   // Inspect
   $inspect = $client->containers()->inspect('container_id');
   

2. Handling Responses: Use ApiException for error handling:

   try {
       $logs = $client->containers()->logs('container_id');
   } catch (ApiException $e) {
       echo "Error: " . $e->getMessage();
   }
   

3. Pagination: Leverage listContainers() with limit and offset:

   $containers = $client->containers()->listContainers(['limit' => 10, 'offset' => 0]);
   

4. Async Operations: Use wait() for container lifecycle events:

   $result = $client->containers()->wait('container_id');
   

Integration Tips

• Laravel Service Provider: Bind the client to the container for dependency injection:

  $this->app->singleton(Client::class, function () {
      return new Client();
  });
  

  Then inject Client into controllers/services.

• Environment Configuration: Override Docker host/port via constructor:

  $client = new Client('unix:///var/run/docker.sock'); // Unix socket
  // or
  $client = new Client('tcp://127.0.0.1:2375'); // TCP
  

• Logging: Enable debug logging for API calls:

  $client = new Client(['basePath' => 'unix:///var/run/docker.sock', 'debug' => true]);
  

Gotchas and Tips

Pitfalls

1. Version Mismatch:

   • The package does not follow SemVer. Version v6.1.40.0 targets Docker API v1.40 with jane-php v6.x.
   • Fix: Pin the exact version in composer.json to avoid breaking changes:

     "docker-client/open-api": "v6.1.40.0"
     

2. Deprecated Endpoints:

   • Some Docker API endpoints (e.g., /containers/{id}/attach/ws) are WebSocket-only and may not work with this client.
   • Workaround: Use raw HTTP requests or switch to a WebSocket library for these cases.

3. Authentication:

   • The client does not handle TLS/HTTPS auth by default. For remote Docker daemons:

     $client = new Client('https://user:pass@host:2376', [
         'verifyPeer' => false, // Disable if using self-signed certs (not recommended)
     ]);
     

4. Rate Limiting:

   • Docker daemons may throttle requests. Implement retries with exponential backoff:

     use GuzzleHttp\Exception\RequestException;
     
     try {
         $client->containers()->listContainers();
     } catch (RequestException $e) {
         if ($e->getCode() === 429) {
             sleep(2); // Retry after 2 seconds
             retry();
         }
     }
     

Debugging Tips

1. Enable Debug Mode:

   $client = new Client(['debug' => true]);
   

   Logs will show raw API requests/responses.

2. Inspect Raw Responses: Use getLastResponse() to debug:

   $response = $client->containers()->listContainers();
   echo $client->getLastResponse()->getBody();
   

3. Common Errors:

   • 404 Not Found: Verify container IDs or endpoint paths (e.g., /containers/{id} vs /containers/{name}).
   • 500 Internal Server Error: Check Docker daemon logs (journalctl -u docker or docker logs <daemon-container>).

Extension Points

1. Custom API Clients: Extend Docker\Client to add domain-specific methods:

   class CustomClient extends Client {
       public function restartAllContainers() {
           $containers = $this->containers()->listContainers();
           foreach ($containers as $container) {
               $this->containers()->restart($container['Id']);
           }
       }
   }
   

2. Override HTTP Client: Replace the default Guzzle client for custom behavior (e.g., middleware):

   use GuzzleHttp\Client as GuzzleClient;
   
   $guzzle = new GuzzleClient([
       'timeout' => 30,
       'headers' => ['User-Agent' => 'MyApp/1.0'],
   ]);
   
   $client = new Client(['httpClient' => $guzzle]);
   

3. Add New Endpoints: If missing an endpoint, generate it manually using the OpenAPI spec and the Jane PHP generator.