feat: allow overriding Docker API version

Author: Rid

README.md

@@ -20,8 +20,17 @@ composer require beluga-php/docker-php
 
 ## Docker API Version
 
-By default it will use the last version of docker api available, if you want to fix a version (like 1.41) you can add this
-requirement to composer:
+Each release line targets a Docker API version. The 1.45 client uses API v1.45 by default.
+
+You can override the version used in request URLs when connecting to a Docker daemon that no longer accepts v1.45:
+
+```bash
+DOCKER_API_VERSION=1.52 php your-script.php
+```
+
+This only changes the API version in request URLs. The generated models and endpoints still use the v1.45 specification.
+
+To use an older API specification, install the matching API package:
 
 ```bash
 composer require "beluga-php/docker-php-api:6.1.41.*"

src/DockerClientFactory.php

@@ -26,6 +26,10 @@ public static function create(array $config = [], ?PluginClientFactory $pluginCl
 
         $uriFactory = Psr17FactoryDiscovery::findUriFactory();
         $host = preg_match('/unix:\/\//', $config['remote_socket']) ? 'http://localhost' : $config['remote_socket'];
+        $dockerApiVersion = ltrim(getenv('DOCKER_API_VERSION') ?: 'v1.45', '/');
+        if (!str_starts_with($dockerApiVersion, 'v')) {
+            $dockerApiVersion = 'v'.$dockerApiVersion;
+        }
 
         $pluginClientFactory ??= new PluginClientFactory();
 
@@ -34,7 +38,7 @@ public static function create(array $config = [], ?PluginClientFactory $pluginCl
             [
                 new ContentLengthPlugin(),
                 new DecoderPlugin(),
-                new AddPathPlugin($uriFactory->createUri('/v1.45')),
+                new AddPathPlugin($uriFactory->createUri('/'.$dockerApiVersion)),
                 new AddHostPlugin($uriFactory->createUri($host)),
                 new HeaderDefaultsPlugin([
                     'host' => parse_url($host, \PHP_URL_HOST),

tests/DockerClientFactoryTest.php

@@ -5,13 +5,22 @@
 namespace Docker\Tests;
 
 use Docker\DockerClientFactory;
+use Http\Client\Common\Plugin\AddPathPlugin;
+use Http\Client\Common\PluginClient;
+use Http\Client\Common\PluginClientFactory;
 use Psr\Http\Client\ClientInterface;
 
 class DockerClientFactoryTest extends TestCase
 {
     protected function tearDown(): void
     {
         parent::tearDown();
+        PluginClientFactory::setFactory(static function ($client, array $plugins, array $options): PluginClient {
+            unset($options['client_name']);
+
+            return new PluginClient($client, $plugins, $options);
+        });
+        putenv('DOCKER_API_VERSION');
         putenv('DOCKER_TLS_VERIFY');
     }
 
@@ -20,6 +29,32 @@ public function testStaticConstructor(): void
         $this->assertInstanceOf(ClientInterface::class, DockerClientFactory::create());
     }
 
+    public function testDefaultApiVersion(): void
+    {
+        $this->assertSame('/v1.45', $this->getApiPath());
+    }
+
+    public function testApiVersionFromEnvironment(): void
+    {
+        putenv('DOCKER_API_VERSION=v1.52');
+
+        $this->assertSame('/v1.52', $this->getApiPath());
+    }
+
+    public function testApiVersionWithLeadingSlash(): void
+    {
+        putenv('DOCKER_API_VERSION=/v1.52');
+
+        $this->assertSame('/v1.52', $this->getApiPath());
+    }
+
+    public function testApiVersionWithoutVersionPrefix(): void
+    {
+        putenv('DOCKER_API_VERSION=1.52');
+
+        $this->assertSame('/v1.52', $this->getApiPath());
+    }
+
     public function testCreateFromEnvWithoutCertPath(): void
     {
         $this->expectException(\RuntimeException::class);
@@ -68,4 +103,27 @@ public function testCreateCustomPeerName(): void
         $this->assertSame('/abc/key.pem', $context['ssl']['local_pk']);
         $this->assertSame('test', $context['ssl']['peer_name']);
     }
+
+    private function getApiPath(): string
+    {
+        $plugins = [];
+        PluginClientFactory::setFactory(static function ($client, array $createdPlugins, array $options) use (&$plugins): PluginClient {
+            $plugins = $createdPlugins;
+            unset($options['client_name']);
+
+            return new PluginClient($client, $createdPlugins, $options);
+        });
+
+        DockerClientFactory::create();
+
+        foreach ($plugins as $plugin) {
+            if ($plugin instanceof AddPathPlugin) {
+                $uri = (new \ReflectionProperty($plugin, 'uri'))->getValue($plugin);
+
+                return $uri->getPath();
+            }
+        }
+
+        $this->fail('The Docker API path plugin was not configured.');
+    }
 }