Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require docker-client/client-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Docker\ClientBundle\DockerClientBundle::class => ['all' => true],
   ];
   

2. Configuration Define Docker connection settings in config/packages/docker_client.yaml:

   docker_client:
       host: 'unix:///var/run/docker.sock' # Default for local Docker
       # host: 'tcp://127.0.0.1:2375' # Alternative for remote/TCP
       version: 'auto' # or '1.41'
   

3. First Use Case: List Containers Inject the client in a service/controller:

   use Docker\ClientBundle\Client\ClientInterface;
   
   class ContainerService {
       public function __construct(private ClientInterface $client) {}
   
       public function listContainers(): array {
           return $this->client->containers()->list();
       }
   }
   

Implementation Patterns

Common Workflows

1. Container Management

   • Create/Run:

     $container = $this->client->containers()->create([
         'Image' => 'nginx:latest',
         'Cmd' => ['nginx', '-g', 'daemon off;'],
         'name' => 'my-nginx',
     ]);
     $container->start();
     

   • Inspect/Logs:

     $inspect = $this->client->containers()->inspect('my-nginx');
     $logs = $this->client->containers()->logs('my-nginx');
     

2. Image Operations

   • Pull/Push:

     $this->client->images()->pull('alpine:latest');
     $this->client->images()->push('my-image', ['tag' => 'latest']);
     

3. Networks/Volumes

   • Create/Connect:

     $network = $this->client->networks()->create([
         'Name' => 'my-network',
         'Driver' => 'bridge',
     ]);
     $this->client->containers()->connect('my-container', $network['Id']);
     

4. Event Streaming

   • Listen to Docker events:

     $events = $this->client->events()->subscribe();
     foreach ($events as $event) {
         // Handle event (e.g., container start/stop)
     }
     

Integration Tips

• Dependency Injection: Prefer injecting ClientInterface over the concrete Client for testability.
• Async Operations: Use execute() for non-blocking commands (e.g., docker exec).
• Error Handling: Wrap calls in try-catch for DockerException:

  try {
      $this->client->containers()->start('nonexistent');
  } catch (DockerException $e) {
      // Handle error (e.g., container not found)
  }
  

Gotchas and Tips

Pitfalls

1. Permission Issues

   • Unix Socket: Ensure the PHP process has read/write access to /var/run/docker.sock (common on shared hosting). Fix: Add user to the docker group or adjust socket permissions:

     sudo chmod 666 /var/run/docker.sock
     

   • TCP Host: If using tcp://, ensure the Docker daemon allows remote connections (/etc/docker/daemon.json):

     {
       "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
     }
     

2. Deprecated Methods

   • The bundle is outdated (last release: 2020). Some docker-client/client methods may have changed.
   • Workaround: Check the upstream docs for breaking changes.

3. Rate Limiting

   • Docker APIs may throttle requests. Implement retries for transient failures:

     use Symfony\Component\Process\Exception\ProcessFailedException;
     
     try {
         $this->client->containers()->start('container');
     } catch (ProcessFailedException $e) {
         if (str_contains($e->getMessage(), '429')) {
             sleep(2); // Retry after delay
             retry();
         }
     }
     

Debugging

• Enable Debugging: Set the DOCKER_CLIENT_DEBUG environment variable to log raw API requests/responses.
• Inspect Raw API Calls: Use the execute() method to debug low-level commands:

  $output = $this->client->execute('container inspect my-container');
  

Extension Points

1. Custom Middleware Override the client factory to add middleware (e.g., auth headers):

   # config/packages/docker_client.yaml
   docker_client:
       client_factory: App\Service\CustomDockerClientFactory
   

   // src/Service/CustomDockerClientFactory.php
   class CustomDockerClientFactory extends ClientFactory {
       protected function createClient(): Client {
           $client = parent::createClient();
           $client->addMiddleware(new CustomAuthMiddleware());
           return $client;
       }
   }
   

2. Event Subscribers Listen to Docker events via Symfony’s event dispatcher:

   use Docker\ClientBundle\Event\DockerEvent;
   
   class DockerEventSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents(): array {
           return [
               DockerEvent::CONTAINER_STARTED => 'onContainerStarted',
           ];
       }
   
       public function onContainerStarted(DockerEvent $event) {
           // Handle event data
       }
   }
   

3. Configuration Overrides Dynamically override settings per environment:

   # config/packages/dev/docker_client.yaml
   docker_client:
       host: 'tcp://docker-dev:2375'