ADR-0002: Use Guzzle as the HTTP Client

Status

Accepted

Context

The library needs to make HTTP requests to Contentful REST APIs. Options considered:

1. Raw cURL / file_get_contents — too low-level; no PSR-7 support, no middleware/handler stack, hard to test.
2. Symfony HTTP Client — excellent PSR-18 compliance but smaller ecosystem footprint in the PHP SDK space at the time of initial design.
3. Guzzle — the de facto standard PHP HTTP client with PSR-7 native support, handler stacks for middleware (used in tests), broad community adoption, and active maintenance through v7.

The test suite relies on Guzzle's HandlerStack to inject mock responses, making it important that the HTTP client is injectable and testable without a real network.

Decision

guzzlehttp/guzzle (^6.5|^7.0) and guzzlehttp/psr7 (^1.6|^2.1.1) are require dependencies. BaseClient accepts an optional ?HttpClient $httpClient constructor argument, allowing consumers to substitute a custom-configured Guzzle instance (e.g., with custom middleware, retry logic, or mock handlers for testing).

Consequences

• Enables: Out-of-the-box HTTP/1.1 with gzip, redirect following, connection pooling via Guzzle, and easy test-time HTTP interception.
• Constrains: Consumers are coupled to Guzzle — switching to a different HTTP client would require a new major version. PSR-18 abstraction was not adopted because it would require re-implementing the handler stack pattern used in tests.
• Trade-off accepted: The broad version range (^6.5|^7.0) allows Laravel 11 compatibility, which requires psr/http-message ^2.0 (added in 4.0.2 changelog).