feat: add PSR-18/PSR-17 HTTP client injection support (#127)

cb-alish · claude · web-flow · commit a8532e4d678c · 2026-03-03T11:54:47.000+05:30
* feat: add PSR-18/PSR-17 HTTP client injection support

Allow injecting a PSR-18 ClientInterface directly into ChargebeeClient
without implementing the Chargebee-specific HttpClientFactory interface.
PSR-17 request/stream factories can optionally be provided; when omitted,
php-http/discovery auto-discovers any installed implementation.

New: src/HttpClient/PsrClientAdapter.php wraps a PSR-18 client and builds
PSR-7 requests using injected or discovered PSR-17 factories.

The existing HttpClientFactory injection path and the default GuzzleFactory
are unchanged — fully backward compatible.

New dependencies (require):
  - php-http/discovery ^1.0
  - psr/http-factory ^1.0

Note: guzzlehttp/guzzle remains in require for v4.x compatibility.
Removing it is deferred to the next major version.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* Version bump

---------

Co-authored-by: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,16 @@
+### v4.18.0 (2025-03-03)
+* * *
+### PSR-18 / PSR-17 HTTP client injection (backward compatible):
+- **Direct PSR-18 injection:** You can now inject a `Psr\Http\Client\ClientInterface` (PSR-18) directly into `ChargebeeClient` without implementing the Chargebee-specific `HttpClientFactory` interface.
+- **Optional PSR-17 factories:** When using a PSR-18 client, you may optionally pass `RequestFactoryInterface` and `StreamFactoryInterface` (PSR-17). When omitted, [php-http/discovery](https://github.com/php-http/discovery) auto-discovers any installed PSR-17 implementation.
+- **New adapter:** `Chargebee\HttpClient\PsrClientAdapter` wraps a PSR-18 client and builds PSR-7 requests using the injected or discovered PSR-17 request/stream factories.
+- **Backward compatibility:** The existing `HttpClientFactory` injection path and the default `GuzzleFactory` are unchanged.
+
+### New dependencies (require):
+- `php-http/discovery` ^1.0
+- `psr/http-factory` ^1.0
+
+
 ### v4.17.0 (2026-03-02)
 * * *
 ### New Resources:
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-4.17.0
+4.18.0
diff --git a/composer.json b/composer.json
@@ -13,7 +13,13 @@
     "require": {
         "php": ">=8.1.0",
         "guzzlehttp/guzzle": ">=7",
-        "psr/http-client": "^1.0"
+        "php-http/discovery": "^1.0",
+        "psr/http-client": "^1.0",
+        "psr/http-factory": "^1.0"
+    },
+    "suggest": {
+        "psr/http-client-implementation": "Any PSR-18 HTTP client (e.g. symfony/http-client) — in a future major version Guzzle will become optional.",
+        "psr/http-factory-implementation": "Any PSR-17 factory (e.g. nyholm/psr7) — required if you inject a PSR-18 client without PSR-17 factories and Guzzle is not installed."
     },
     "autoload": {
         "psr-4": {
@@ -31,5 +37,10 @@
     "require-dev": {
         "phpstan/phpstan": "^2.1",
         "phpunit/phpunit": "^12.3"
+    },
+    "config": {
+        "allow-plugins": {
+            "php-http/discovery": true
+        }
     }
-}
+}
diff --git a/src/ChargebeeClient.php b/src/ChargebeeClient.php
@@ -133,6 +133,10 @@
 
 use Chargebee\HttpClient\GuzzleFactory;
 use Chargebee\HttpClient\HttpClientFactory;
+use Chargebee\HttpClient\PsrClientAdapter;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\RequestFactoryInterface;
+use Psr\Http\Message\StreamFactoryInterface;
 
 class ChargebeeClient {
     private HttpClientFactory $httpClientFactory;
@@ -149,10 +153,18 @@ class ChargebeeClient {
      *      retryConfig?: RetryConfig,
      *      enableDebugLogs?: bool
      * } $options
-     * @param HttpClientFactory|null $httpClient
+     * @param HttpClientFactory|ClientInterface|null $httpClient Pass an HttpClientFactory for full control,
+     *        or a PSR-18 ClientInterface for a simpler injection path. When omitted, GuzzleFactory is used.
+     * @param RequestFactoryInterface|null $requestFactory PSR-17 request factory (used only when $httpClient is a ClientInterface)
+     * @param StreamFactoryInterface|null $streamFactory PSR-17 stream factory (used only when $httpClient is a ClientInterface)
      * @throws \Exception
      */
-    public function __construct($options, ?HttpClientFactory $httpClient=null)
+    public function __construct(
+        $options,
+        HttpClientFactory|ClientInterface|null $httpClient = null,
+        ?RequestFactoryInterface $requestFactory = null,
+        ?StreamFactoryInterface $streamFactory = null,
+    )
     {
         if (!is_array($options)) {
             throw new \Exception('$options must be of type array!');
@@ -183,7 +195,13 @@ public function __construct($options, ?HttpClientFactory $httpClient=null)
             $env->setEnableDebugLogs($options['enableDebugLogs']);
         }
         $this->env = $env;
-        $this->httpClientFactory = $httpClient ?? new GuzzleFactory($env->requestTimeoutInSecs, $env->connectTimeoutInSecs);
+        if ($httpClient instanceof ClientInterface) {
+            $this->httpClientFactory = new PsrClientAdapter($httpClient, $requestFactory, $streamFactory);
+        } elseif ($httpClient instanceof HttpClientFactory) {
+            $this->httpClientFactory = $httpClient;
+        } else {
+            $this->httpClientFactory = new GuzzleFactory($env->requestTimeoutInSecs, $env->connectTimeoutInSecs);
+        }
     }
 
 
diff --git a/src/HttpClient/PsrClientAdapter.php b/src/HttpClient/PsrClientAdapter.php
@@ -0,0 +1,57 @@
+<?php
+
+namespace Chargebee\HttpClient;
+
+use Chargebee\ValueObjects\Transporters\ChargebeePayload;
+use Http\Discovery\Psr17FactoryDiscovery;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\RequestFactoryInterface;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\StreamFactoryInterface;
+
+class PsrClientAdapter implements HttpClientFactory
+{
+    public function __construct(
+        private readonly ClientInterface $client,
+        private readonly ?RequestFactoryInterface $requestFactory = null,
+        private readonly ?StreamFactoryInterface $streamFactory = null,
+    ) {}
+
+    public function create(): ClientInterface
+    {
+        return $this->client;
+    }
+
+    public function createRequest(ChargebeePayload $payload): RequestInterface
+    {
+        $httpMethod = $payload->getHttpMethod();
+        $params     = $payload->getSerializedParameters();
+        $headers    = $payload->getHeaders();
+
+        if (!in_array($httpMethod, ['get', 'post'], true)) {
+            throw new \Exception("Invalid http method $httpMethod");
+        }
+
+        $url = self::utf8($payload->getUrl());
+
+        $requestFactory = $this->requestFactory ?? Psr17FactoryDiscovery::findRequestFactory();
+        $streamFactory  = $this->streamFactory  ?? Psr17FactoryDiscovery::findStreamFactory();
+
+        if ($httpMethod === 'get' && !empty($params)) {
+            $url .= '?' . $params;
+        }
+        $request = $requestFactory->createRequest(strtoupper($httpMethod), $url);
+        foreach ($headers as $name => $value) {
+            $request = $request->withHeader($name, $value);
+        }
+        if ($httpMethod === 'post' && !empty($params)) {
+            $request = $request->withBody($streamFactory->createStream($params));
+        }
+        return $request;
+    }
+
+    private static function utf8(string $value): string
+    {
+        return mb_convert_encoding($value, 'UTF-8');
+    }
+}
diff --git a/src/Version.php b/src/Version.php
@@ -4,7 +4,7 @@
 
 final class Version
 {
-	const VERSION = '4.17.0';
+	const VERSION = '4.18.0';
 }
 
 ?>
diff --git a/tests/Network/PsrClientAdapterTest.php b/tests/Network/PsrClientAdapterTest.php
@@ -0,0 +1,233 @@
+<?php
+
+namespace Tests\Network;
+
+use Chargebee\ChargebeeClient;
+use Chargebee\Environment;
+use Chargebee\HttpClient\PsrClientAdapter;
+use Chargebee\ValueObjects\Transporters\ChargebeePayload;
+use GuzzleHttp\Psr7\Response;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\RequestFactoryInterface;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\StreamFactoryInterface;
+use Psr\Http\Message\StreamInterface;
+use Psr\Http\Message\UriInterface;
+
+#[CoversClass(PsrClientAdapter::class)]
+final class PsrClientAdapterTest extends TestCase
+{
+    private function makePayload(
+        string $method,
+        string $url,
+        ?string $params = null,
+        array $headers = []
+    ): ChargebeePayload {
+        $env = new Environment('test-site', 'test-api-key');
+        return new ChargebeePayload($url, $method, $params, $headers, $env);
+    }
+
+    private function makeStubClient(?ResponseInterface $response = null): ClientInterface
+    {
+        $response ??= new Response(200, [], '{}');
+
+        return new class($response) implements ClientInterface {
+            private ResponseInterface $response;
+            public array $sentRequests = [];
+
+            public function __construct(ResponseInterface $response)
+            {
+                $this->response = $response;
+            }
+
+            public function sendRequest(RequestInterface $request): ResponseInterface
+            {
+                $this->sentRequests[] = $request;
+                return $this->response;
+            }
+        };
+    }
+
+    #[TestDox('PsrClientAdapter::create() returns the injected PSR-18 client')]
+    public function testCreateReturnsInjectedClient(): void
+    {
+        $client = $this->makeStubClient();
+        $adapter = new PsrClientAdapter($client);
+
+        $this->assertSame($client, $adapter->create());
+    }
+
+    #[TestDox('GET request with no PSR-17 factories discovers them automatically')]
+    public function testGetRequestWithDiscoveredFactories(): void
+    {
+        $client = $this->makeStubClient();
+        $adapter = new PsrClientAdapter($client);
+
+        $payload = $this->makePayload('get', 'https://example.com/api/v2/customers', 'limit=10', [
+            'Authorization' => 'Basic dGVzdA==',
+        ]);
+
+        $request = $adapter->createRequest($payload);
+
+        $this->assertSame('GET', strtoupper($request->getMethod()));
+        $this->assertStringContainsString('limit=10', (string) $request->getUri());
+        $this->assertSame('Basic dGVzdA==', $request->getHeaderLine('Authorization'));
+    }
+
+    #[TestDox('POST request with no PSR-17 factories discovers them automatically')]
+    public function testPostRequestWithDiscoveredFactories(): void
+    {
+        $client = $this->makeStubClient();
+        $adapter = new PsrClientAdapter($client);
+
+        $payload = $this->makePayload('post', 'https://example.com/api/v2/customers', 'first_name=John', [
+            'Content-Type' => 'application/x-www-form-urlencoded',
+        ]);
+
+        $request = $adapter->createRequest($payload);
+
+        $this->assertSame('POST', strtoupper($request->getMethod()));
+        $this->assertSame('first_name=John', (string) $request->getBody());
+    }
+
+    #[TestDox('GET request with PSR-17 factories uses them for request building')]
+    public function testGetRequestWithPsr17Factories(): void
+    {
+        $client  = $this->makeStubClient();
+        [$requestFactory, $streamFactory] = $this->makePsr17Factories();
+
+        $adapter = new PsrClientAdapter($client, $requestFactory, $streamFactory);
+
+        $payload = $this->makePayload('get', 'https://example.com/api/v2/customers', 'limit=5', [
+            'Authorization' => 'Basic dGVzdA==',
+        ]);
+
+        $request = $adapter->createRequest($payload);
+
+        $this->assertSame('GET', strtoupper($request->getMethod()));
+        $this->assertStringContainsString('limit=5', (string) $request->getUri());
+        $this->assertSame('Basic dGVzdA==', $request->getHeaderLine('Authorization'));
+    }
+
+    #[TestDox('POST request with PSR-17 factories uses them for request building')]
+    public function testPostRequestWithPsr17Factories(): void
+    {
+        $client  = $this->makeStubClient();
+        [$requestFactory, $streamFactory] = $this->makePsr17Factories();
+
+        $adapter = new PsrClientAdapter($client, $requestFactory, $streamFactory);
+
+        $payload = $this->makePayload('post', 'https://example.com/api/v2/customers', 'first_name=Jane', [
+            'Content-Type' => 'application/x-www-form-urlencoded',
+        ]);
+
+        $request = $adapter->createRequest($payload);
+
+        $this->assertSame('POST', strtoupper($request->getMethod()));
+        $this->assertSame('first_name=Jane', (string) $request->getBody());
+    }
+
+    #[TestDox('Invalid HTTP method throws an exception')]
+    public function testInvalidHttpMethodThrows(): void
+    {
+        $client  = $this->makeStubClient();
+        $adapter = new PsrClientAdapter($client);
+
+        $payload = $this->makePayload('delete', 'https://example.com/api/v2/customers/123');
+
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessageMatches('/Invalid http method delete/i');
+
+        $adapter->createRequest($payload);
+    }
+
+    #[TestDox('Existing HttpClientFactory injection still works (regression)')]
+    public function testExistingHttpClientFactoryInjectionStillWorks(): void
+    {
+        $mockFactory = new MockGuzzleFactory(
+            1.0,
+            3.0,
+            [],
+            200,
+            '{"list":[],"next_offset":null}'
+        );
+
+        $chargebeeClient = new ChargebeeClient([
+            'site'   => 'test-site',
+            'apiKey' => 'test-api-key',
+        ], $mockFactory);
+
+        // Verify no exception is thrown during construction
+        $this->assertInstanceOf(ChargebeeClient::class, $chargebeeClient);
+    }
+
+    #[TestDox('PSR-18 ClientInterface can be injected directly into ChargebeeClient')]
+    public function testPsrClientInterfaceInjectionIntoChargebeeClient(): void
+    {
+        $stubClient = $this->makeStubClient(
+            new Response(200, [], '{"list":[],"next_offset":null}')
+        );
+
+        $chargebeeClient = new ChargebeeClient([
+            'site'   => 'test-site',
+            'apiKey' => 'test-api-key',
+        ], $stubClient);
+
+        $this->assertInstanceOf(ChargebeeClient::class, $chargebeeClient);
+    }
+
+    #[TestDox('PSR-18 + PSR-17 factories can be injected into ChargebeeClient')]
+    public function testPsrClientWithFactoriesInjectionIntoChargebeeClient(): void
+    {
+        $stubClient = $this->makeStubClient(
+            new Response(200, [], '{"list":[],"next_offset":null}')
+        );
+        [$requestFactory, $streamFactory] = $this->makePsr17Factories();
+
+        $chargebeeClient = new ChargebeeClient([
+            'site'   => 'test-site',
+            'apiKey' => 'test-api-key',
+        ], $stubClient, $requestFactory, $streamFactory);
+
+        $this->assertInstanceOf(ChargebeeClient::class, $chargebeeClient);
+    }
+
+    /**
+     * Returns minimal anonymous-class implementations of PSR-17 factories
+     * backed by Guzzle PSR-7 objects, so no extra test dependency is needed.
+     *
+     * @return array{RequestFactoryInterface, StreamFactoryInterface}
+     */
+    private function makePsr17Factories(): array
+    {
+        $requestFactory = new class implements RequestFactoryInterface {
+            public function createRequest(string $method, $uri): RequestInterface
+            {
+                return new \GuzzleHttp\Psr7\Request($method, $uri);
+            }
+        };
+
+        $streamFactory = new class implements StreamFactoryInterface {
+            public function createStream(string $content = ''): StreamInterface
+            {
+                return \GuzzleHttp\Psr7\Utils::streamFor($content);
+            }
+
+            public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
+            {
+                return \GuzzleHttp\Psr7\Utils::streamFor(fopen($filename, $mode));
+            }
+
+            public function createStreamFromResource($resource): StreamInterface
+            {
+                return \GuzzleHttp\Psr7\Utils::streamFor($resource);
+            }
+        };
+
+        return [$requestFactory, $streamFactory];
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`
`5`	`5`	`final class Version`
`6`	`6`	`{`
`7`		`- const VERSION = '4.17.0';`
	`7`	`+ const VERSION = '4.18.0';`
`8`	`8`	`}`
`9`	`9`
`10`	`10`	`?>`