Docker Util Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require cscfa_tool_division/docker_util
   

   Ensure your project uses Symfony components (Laravel does via symfony/http-foundation and symfony/console).

2. First Use Case: Basic Docker CLI Wrapper Initialize the Docker client in a Laravel service or command:

   use CSCFA\ToolDivision\DockerUtil\DockerClient;
   
   $client = new DockerClient();
   $containers = $client->ps(); // List running containers
   

3. Key Files to Review

   • src/DockerClient.php – Core abstraction for Docker API calls.
   • src/Exception/DockerException.php – Error handling.
   • tests/ – Example usage and edge cases.

Implementation Patterns

Workflows

1. Container Management Use the client to orchestrate containers in Laravel tasks (e.g., migrations, queues):

   $client->run('nginx:alpine', ['-d', '--name', 'laravel-nginx']);
   $client->exec('laravel-nginx', 'nginx -g "daemon off;"');
   

2. Artisan Command Integration Create a custom Artisan command to manage Dockerized services:

   use Illuminate\Console\Command;
   use CSCFA\ToolDivision\DockerUtil\DockerClient;
   
   class DockerDeployCommand extends Command {
       protected $client;
   
       public function __construct(DockerClient $client) {
           parent::__construct();
           $this->client = $client;
       }
   
       public function handle() {
           $this->client->build('Dockerfile', ['t', 'laravel-app']);
           $this->client->up('laravel-app');
       }
   }
   

3. Service Container Binding Bind the DockerClient to Laravel’s IoC container in AppServiceProvider:

   $this->app->singleton(DockerClient::class, function ($app) {
       return new DockerClient(['host' => 'tcp://docker-host:2375']);
   });
   

Integration Tips

• Environment Awareness: Use Laravel’s .env to configure Docker host/port:

  DOCKER_HOST=tcp://docker-host:2375
  

  Inject via constructor:

  $client = new DockerClient(['host' => env('DOCKER_HOST')]);
  

• Logging: Wrap Docker calls in Laravel’s log:

  try {
      $client->logs('container-id');
  } catch (\Exception $e) {
      \Log::error("Docker error: " . $e->getMessage());
  }
  

• Async Tasks: Use Laravel Queues to defer Docker operations:

  Dispatch(new HandleDockerTask($client, 'container-id', 'stop'));
  

Gotchas and Tips

Pitfalls

1. Deprecated Docker API The package uses docker-php (last updated 2016), which may not support newer Docker APIs (e.g., v4+). Validate compatibility with your Docker version.

2. Authentication Issues If using remote Docker hosts, ensure credentials are configured:

   $client = new DockerClient([
       'host' => 'tcp://user:pass@docker-host:2375',
   ]);
   

3. Error Handling Docker exceptions may not bubble up predictably. Extend DockerException for custom handling:

   try {
       $client->pull('image');
   } catch (DockerException $e) {
       if ($e->getCode() === 404) {
           // Handle "image not found"
       }
   }
   

Debugging

• Verbose Output: Enable debug mode for raw Docker CLI output:

  $client->setDebug(true);
  $client->ps(); // Shows underlying CLI commands
  

• Timeouts: Docker operations may hang. Set timeouts explicitly:

  $client->setTimeout(30); // 30 seconds
  

Extension Points

1. Custom Commands Extend DockerClient to add missing commands (e.g., system prune):

   class ExtendedDockerClient extends DockerClient {
       public function prune() {
           return $this->execute('system prune -f');
       }
   }
   

2. Event Listeners Trigger Laravel events on Docker state changes (e.g., container up/down):

   $client->on('container-up', function ($container) {
       event(new ContainerStarted($container));
   });
   

3. Configuration Override default Docker socket path (e.g., for Docker Desktop):

   $client = new DockerClient(['unix_socket' => '/tmp/docker.sock']);