Docker Api Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**: Add the bundle via Composer:
   ```bash
   composer require connectholland/docker-api-bundle

2. Environment Configuration: Define Docker Hub credentials in .env:

   DOCKER_API_USERNAME=your_docker_username
   DOCKER_API_TOKEN=your_docker_token_or_password
   

3. Autowire the Client: Inject ConnectHolland\DockerApiBundle\Api\Client into your service/controller. Example:

   use ConnectHolland\DockerApiBundle\Api\Client;
   
   class MyController {
       public function __construct(private Client $client) {}
   }
   

4. First Use Case: Search for repositories or images:

   $repositories = $this->client->findRepositories('laravel');
   $images = $this->client->findImages('nginx');
   

Where to Look First

• Documentation: Check the CONTRIBUTING.md for incomplete API details.
• Client Methods: Explore the Client class for available methods (e.g., findRepositories, findImages).
• Symfony Integration: Ensure the bundle is registered in config/bundles.php (though autoloading should handle this).

Implementation Patterns

Common Workflows

1. Repository Search:

   $results = $this->client->findRepositories('search-term');
   // Process results (e.g., iterate over $results['results']).
   

2. Image Search:

   $images = $this->client->findImages('image-name');
   // Filter or fetch details from $images.
   

3. Pagination Handling: The API likely returns paginated results. Use next or offset parameters if supported:

   $nextPage = $this->client->findRepositories('search-term', ['page' => 2]);
   

Integration Tips

• Error Handling: Wrap API calls in try-catch blocks to handle authentication or rate-limiting errors:

  try {
      $data = $this->client->findRepositories('term');
  } catch (\ConnectHolland\DockerApiBundle\Exception\ApiException $e) {
      // Log or retry logic.
  }
  

• Caching: Cache responses for frequently accessed data (e.g., popular repositories):

  $cacheKey = 'docker_repos_laravel';
  if (!$repos = $this->cache->get($cacheKey)) {
      $repos = $this->client->findRepositories('laravel');
      $this->cache->set($cacheKey, $repos, '1 hour');
  }
  

• Dependency Injection: Prefer constructor injection for the Client to ensure testability and clarity.

Advanced Usage

• Custom Endpoints: If the bundle supports custom registry URLs, configure via environment variables or DI:

  # config/packages/connect_holland_docker_api.yaml
  connect_holland_docker_api:
      registry_url: 'https://custom-registry.example.com/v2/'
  

• Event Listeners: Extend functionality by listening to Docker API events (if the bundle emits them).

Gotchas and Tips

Pitfalls

1. Incomplete API:

   • The bundle lacks full Docker API coverage. Refer to CONTRIBUTING.md to check supported endpoints.
   • Example: Pulling images or managing repositories may not be supported. Use the official Docker SDK (docker/docker) as a fallback.

2. Authentication Issues:

   • Ensure DOCKER_API_TOKEN is a password or access token (not a refresh token). Docker Hub may reject invalid tokens.
   • Test credentials with curl first:

     curl -u "$DOCKER_API_USERNAME:$DOCKER_API_TOKEN" https://hub.docker.com/v2/repositories/library/
     

3. Rate Limiting:

   • Docker Hub enforces rate limits (~100 requests/hour for anonymous users). Cache responses aggressively or use a personal access token.

4. Archived Status:

   • The package is archived, meaning no new features or bug fixes will be added. Use with caution in production.

Debugging

• Enable Debug Mode: Set DOCKER_API_DEBUG=true in .env to log API requests/responses.
• Check HTTP Status Codes: Use Symfony’s HttpClient or Guzzle middleware to inspect raw responses:

  $this->client->getHttpClient()->getEventDispatcher()->addListener(
      'request',
      function (RequestEvent $event) {
          // Log request details.
      }
  );
  

• Symfony Profiler: If using Symfony, enable the profiler to inspect the Client service calls.

Tips

1. Fallback to Official SDK: For unsupported features, integrate the official Docker SDK:

   composer require docker/docker
   

   Example:

   use Docker\AutomatedBuilder\DockerClient;
   
   $client = DockerClient::create();
   $images = $client->imagesList();
   

2. Environment-Specific Config: Use Symfony’s parameter bag to override settings per environment:

   # config/packages/dev/connect_holland_docker_api.yaml
   connect_holland_docker_api:
       registry_url: 'https://registry-1.docker.io' # Override for dev
   

3. Testing: Mock the Client in tests to avoid hitting Docker Hub:

   $this->mockBuilder()
        ->disableOriginalConstructor()
        ->getMockBuilder(Client::class)
        ->disableOriginalConstructor()
        ->addMethods(['findRepositories'])
        ->getMock();
   

4. Extension Points:

   • Custom Responses: Extend the Client to transform responses (e.g., flatten nested data).
   • Retry Logic: Implement exponential backoff for transient failures using Symfony’s RetryStrategy.

---