feat: set tc-php/<version> User-Agent header for Docker API requests

composer.json

@@ -16,7 +16,8 @@
     "require": {
         "ext-curl": "*",
         "php": ">= 8.1",
-        "beluga-php/docker-php": "^1.45"
+        "beluga-php/docker-php": "^1.45",
+        "php-http/client-common": "^2.7"
     },
     "require-dev": {
         "ext-pdo": "*",

src/ContainerClient/DockerContainerClient.php

@@ -4,7 +4,12 @@
 
 namespace Testcontainers\ContainerClient;
 
+use Composer\InstalledVersions;
 use Docker\Docker as DockerClient;
+use Docker\DockerClientFactory;
+use Http\Client\Common\Plugin\HeaderDefaultsPlugin;
+use Http\Client\Common\PluginClient;
+use Psr\Http\Client\ClientInterface;
 
 class DockerContainerClient
 {
@@ -13,6 +18,18 @@ class DockerContainerClient
      */
     private static ?DockerClient $dockerClient = null;
 
+    /**
+     * @var (callable(): ClientInterface)|null Factory for the base HTTP client.
+     *     When null, DockerClientFactory::createFromEnv() is used.
+     */
+    private static $httpClientFactory = null;
+
+    /**
+     * @var (callable(ClientInterface): DockerClient)|null Factory for the Docker client.
+     *     When null, DockerClient::create() is used.
+     */
+    private static $dockerClientFactory = null;
+
     private function __construct()
     {
     }
@@ -26,19 +43,93 @@ private function __construct()
     public static function getDockerClient(): DockerClient
     {
         if (self::$dockerClient === null) {
-            self::$dockerClient = DockerClient::create();
+            $version = static::resolveVersion();
+
+            $baseHttpClient = self::createHttpClient();
+
+            $httpClient = new PluginClient(
+                $baseHttpClient,
+                [new HeaderDefaultsPlugin(['User-Agent' => 'tc-php/' . $version])]
+            );
+
+            self::$dockerClient = self::createDockerClient($httpClient);
         }
 
         return self::$dockerClient;
     }
 
+    /**
+     * Resolves the package version string used in the User-Agent header.
+     *
+     * Returns the pretty version of the installed package, with the
+     * '+no-version-set' build-metadata suffix stripped. Falls back to
+     * 'unknown' if the package is not found in the Composer runtime data.
+     *
+     * @param string $package Composer package name to resolve; override in tests
+     *                        to exercise the OutOfBoundsException fallback path.
+     */
+    protected static function resolveVersion(string $package = 'testcontainers/testcontainers'): string
+    {
+        try {
+            $version = InstalledVersions::getPrettyVersion($package) ?? 'unknown';
+        } catch (\OutOfBoundsException) {
+            $version = 'unknown';
+        }
+
+        return str_replace('+no-version-set', '', $version);
+    }
+
+    /**
+     * Returns the base HTTP client, using the injected factory if set.
+     */
+    private static function createHttpClient(): ClientInterface
+    {
+        return self::$httpClientFactory !== null
+            ? (self::$httpClientFactory)()
+            : DockerClientFactory::createFromEnv();
+    }
+
+    /**
+     * Builds the DockerClient from the given HTTP client, using the injected factory if set.
+     */
+    private static function createDockerClient(ClientInterface $httpClient): DockerClient
+    {
+        return self::$dockerClientFactory !== null
+            ? (self::$dockerClientFactory)($httpClient)
+            : DockerClient::create($httpClient);
+    }
+
     /**
      * Injects a DockerClient instance for testing or special use cases.
+     * Note: clients injected via this method will not have the tc-php User-Agent header applied automatically.
      *
      * @param DockerClient $client The DockerClient instance to set.
      */
     public static function setDockerClient(DockerClient $client): void
     {
         self::$dockerClient = $client;
     }
+
+    /**
+     * Resets the injectable factories to their defaults.
+     * For use in tests only — do not call in production code.
+     *
+     * @param (callable(): ClientInterface)|null $httpClientFactory
+     * @param (callable(ClientInterface): DockerClient)|null $dockerClientFactory
+     */
+    public static function setFactories(?callable $httpClientFactory, ?callable $dockerClientFactory): void
+    {
+        self::$httpClientFactory = $httpClientFactory;
+        self::$dockerClientFactory = $dockerClientFactory;
+    }
+
+    /**
+     * Resets the injectable factories to their defaults (both null).
+     * For use in tests only — do not call in production code.
+     */
+    public static function resetFactories(): void
+    {
+        self::$httpClientFactory = null;
+        self::$dockerClientFactory = null;
+    }
 }