Docker Php Api Laravel Package

Getting Started

Minimal Steps

1. Avoid Direct Usage: The package explicitly states not to use it directly—instead, rely on docker-php/docker, which depends on this generated API client.
2. Install via Docker-PHP:

   composer require docker-php/docker
   

   This pulls the API client as a dependency automatically.
3. First Use Case:

   use Docker\Docker;
   $client = new Docker('unix:///var/run/docker.sock');
   $containers = $client->listContainers();
   print_r($containers);
   

   Verify Docker daemon connectivity and API responses.

Where to Look First

• Docker-PHP Docs: https://github.com/docker-php/docker (primary usage guide).
• Generated API: Browse the src folder for raw OpenAPI-generated classes (e.g., Container, Image).
• OpenAPI Spec: Docker API Spec for reference.
• Release Notes: Check the changelog to see which Docker Engine API version the tag targets (current line: v1.56, release 7.1.56.x).

Implementation Patterns

Core Workflows

1. Container Management:

   // Pull an image
   $client->pull('nginx:latest');
   
   // Run a container
   $container = $client->run('nginx:latest', ['detach' => true]);
   
   // Inspect container
   $inspect = $client->inspectContainer($container['Id']);
   

2. Image Operations:

   // List images
   $images = $client->listImages(['all' => true]);
   
   // Build from Dockerfile
   $client->buildImage('/path/to/Dockerfile', ['tag' => 'my-image']);
   

3. Networks/Volumes:

   // Create a network
   $network = $client->createNetwork(['Name' => 'my-net']);
   
   // List volumes
   $volumes = $client->listVolumes();
   

Integration Tips

• Error Handling: Wrap API calls in try-catch:

  try {
      $client->stopContainer($containerId);
  } catch (\Docker\Exception $e) {
      Log::error("Docker error: " . $e->getMessage());
  }
  

• Async Operations: Use callbacks for long-running tasks (e.g., buildImage):

  $client->buildImage($path, ['tag' => 'my-image'], function ($output) {
      echo $output['stream'] ?? '';
  });
  

• Configuration: Pass custom Docker host/port:

  $client = new Docker('tcp://192.168.99.100:2376', [
      'ssl' => true,
      'certPath' => '/path/to/certs'
  ]);
  

Laravel-Specific Patterns

1. Service Provider Binding:

   // app/Providers/DockerServiceProvider.php
   public function register()
   {
       $this->app->singleton('docker', function () {
           return new Docker(config('services.docker.host', 'unix:///var/run/docker.sock'));
       });
   }
   

2. Artisan Commands:

   // app/Console/Commands/RebuildDocker.php
   protected $docker;
   public function __construct(Docker $docker) { $this->docker = $docker; }
   
   public function handle()
   {
       $this->docker->buildImage('/path/to/Dockerfile', ['tag' => 'app']);
   }
   

3. Queue Jobs:

   // app/Jobs/DeployContainer.php
   public function handle(Docker $docker)
   {
       $docker->run('app-image', ['detach' => true, 'name' => 'app-container']);
   }
   

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The package is archived and not maintained beyond generated-code refreshes. Use docker-php/docker (which depends on this) instead.
   • Risk: Breaking changes if Docker API evolves past the generated line (currently v1.56). Newer Engine features beyond v1.56 will not be available until a new tag is generated.

2. Versioning Quirks:

   • Tag format: MAJOR.MINOR.DOCKER_API_VERSION.PATCH (e.g., 7.1.56.3 = Docker Engine API v1.56, patch 3).
   • Pin the whole API line, not just the last number — patches within a line only regenerate code / metadata and never change the API surface:

     composer require docker-php/docker-php-api:">=7.1.56.0 <7.1.57.0"
     # equivalently: 7.1.56.*
     

   • Patch releases are safe to absorb: 7.1.56.3 vs 7.1.56.2 only removed the funding entry from composer.json; generated code and dependency constraints are identical. No code changes required to upgrade.
   • If you are still on an older line (e.g. 4.1.25.*), upgrading to 7.1.56.* is a real change: request/response models track a much newer Engine API. Re-run your integration tests against the daemon version you deploy.

3. SSL/TLS Issues:

   • If using tcp://, ensure certificates are properly configured:

     $client = new Docker('tcp://host:2376', [
         'ssl' => true,
         'certPath' => '/path/to/certs',
         'caPath' => '/path/to/ca.pem'
     ]);
     

4. Rate Limiting:

   • Docker API may throttle requests. Implement retries:

     use Docker\Exception\DockerException;
     $attempts = 0;
     do {
         try { return $client->listContainers(); }
         catch (DockerException $e) {
             if (++$attempts >= 3) throw $e;
             sleep(1);
         }
     } while (true);
     

5. Platform-Specific Paths:

   • Docker socket paths vary:
     • Linux: unix:///var/run/docker.sock
     • macOS (Docker Desktop): unix:///Users/$USER/.docker/run/docker.sock
     • Windows (WSL2): unix:///mnt/c/users/$USER/.docker/run/docker.sock

6. Daemon/Client API Mismatch:

   • The generated client targets Engine API v1.56. Calling newer endpoints on an older daemon returns 404/400; calling older daemons from a newer client is generally tolerated, but pin your client line to the daemon you actually run in CI and production.

Debugging

• Enable Debug Mode:

  $client->setDebug(true); // Logs raw API requests/responses
  

• Check Docker Daemon Logs:

  journalctl -u docker.service -f  # Systemd
  docker logs <container-id>       # Container logs
  

• Validate API Responses: Use var_dump() or print_r() to inspect raw responses:

  $response = $client->inspectContainer($id);
  var_dump($response->getStatusCode(), $response->getBody());
  

• Confirm What You Have Installed:

  composer show docker-php/docker-php-api   # shows 7.1.56.x and the resolved API line
  

Extension Points

1. Custom API Endpoints: Override the client to extend unsupported endpoints:

   $client->get('/_ping', [], 'GET'); // Raw API call
   

2. Middleware: Add request/response filters:

   $client->addMiddleware(function ($request) {
       $request->setHeader('X-Custom-Header', 'value');
   });
   

3. Mocking for Tests: Use GuzzleHttp\HandlerStack to mock responses:

   $handler = HandlerStack::create();
   $handler->push(Middleware::tap(function ($request) {
       return new Response(200, [], json_encode(['Id' => 'test-id']));
   }));
   $client->setHandler($handler);
   

Performance Tips

• Reuse Connections: Instantiate $client once (e.g., as a singleton).
• Batch Operations: Use listContainers() with filters instead of multiple inspectContainer() calls.
• Streaming: For large outputs (e.g., logs), stream responses:

  $client->getContainerLogs($id, [
      'follow' => true,
      'stdout' => true,
      'stream' => true
  ], function ($chunk) {
      echo $chunk;
  });