Symfony HttpClient Contracts

Symfony HttpClient Contracts is a set of interfaces extracted from Symfony’s HttpClient component, letting libraries depend on an HTTP client abstraction rather than a specific implementation. The core HttpClientInterface defines a single request() method returning a lazy ResponseInterface whose status, headers, and body are only fetched when accessed, plus stream() for reading multiple responses concurrently and withOptions() for cloning a client with new defaults.

It is one of Symfony’s *-contracts packages, published to decouple public component APIs from their concrete implementations so any compliant client (Symfony’s own, or a third-party adapter) can be swapped in transparently.

What You Get

• HttpClientInterface with a documented OPTIONS_DEFAULTS contract covering auth, headers, body, JSON, redirects, timeouts, TLS, and proxy options
• Lazy ResponseInterface/ResponseStreamInterface/ChunkInterface for reading status, headers, and body only when accessed
• A standardized exception hierarchy (TransportExceptionInterface, HttpExceptionInterface, TimeoutExceptionInterface, etc.)
• Test\HttpClientTestCase, a reusable PHPUnit reference suite for validating any implementation’s compliance

Common Use Cases

• Library authors who need to make HTTP requests without hard-depending on Symfony’s HttpClient implementation or any other specific client
• Packages that want to support dependency injection of any conforming HTTP client (Symfony’s, Guzzle adapters, mocks) for testability
• Implementers building a new HTTP client that want a battle-tested contract plus a ready-made compliance test suite

Under The Hood

Architecture — HttpClientInterface::request() returns a ResponseInterface immediately without blocking; implementations must defer the actual network I/O until a response property (status code, headers, content) is read, which is what enables true concurrency — many requests can be issued before any of them resolve. stream() accepts one or more responses and yields chunks as they arrive across all of them, and withOptions() returns a new client instance with merged default options rather than mutating the original, keeping clients immutable and safely shareable.

Tech Stack — PHP 8.1+, PSR-4 autoloaded under Symfony\Contracts\HttpClient. It has zero runtime dependencies — a deliberate design choice so any package can depend on the contracts without dragging in Symfony’s full HttpClient stack (which itself depends on symfony/http-client-contracts, psr/log, and cURL/stream bindings).

Code Quality — Rather than unit tests in this repo, the package ships Test/HttpClientTestCase, an abstract PHPUnit test case with dozens of test methods (redirects, timeouts, auth, streaming, TLS, DNS overrides) that concrete implementations extend and run against their own client — a compliance-suite pattern rather than testing the interfaces themselves, which have no behavior to test.

API Design — The single-method request(string $method, string $url, array $options = []) signature keeps the day-to-day API minimal while OPTIONS_DEFAULTS documents the full extensibility surface inline via PHPDoc comments on each key, functioning as living documentation for every implementation to honor consistently.