Symfony HttpClient

Symfony HttpClient is the HTTP client component from the Symfony framework, providing a unified API for making synchronous and asynchronous HTTP requests from PHP. It wraps native cURL bindings (via CurlHttpClient) with a pure-PHP stream fallback (NativeHttpClient), giving it near-zero overhead while still supporting HTTP/2 multiplexing, concurrent requests, and streaming responses without blocking.

Beyond the base transport, the component ships decorators for retries, caching, throttling, mocking in tests, and PSR-18/HTTPlug interoperability, making it usable both as a standalone client and as a drop-in replacement for Guzzle in libraries that expect a PSR-compliant HTTP client.

What You Get

• A unified HttpClientInterface with both synchronous and asynchronous request semantics
• Native cURL transport (CurlHttpClient) supporting HTTP/2 push and multiplexed concurrent requests
• A pure-PHP fallback (NativeHttpClient) for environments without the cURL extension
• Built-in decorators for retry logic, response caching, throttling, and request/response tracing
• PSR-18 and HTTPlug adapters (Psr18Client, HttplugClient) for drop-in compatibility with libraries expecting those interfaces
• A MockHttpClient for deterministic HTTP testing without network calls

Common Use Cases

• Calling third-party REST APIs from a Symfony (or any PHP) application with automatic retries and timeouts
• Streaming large HTTP responses (downloads, server-sent events) without loading the full body into memory
• Firing off many concurrent outbound requests (e.g. webhook fan-out or multi-source aggregation) using async/multiplexed I/O
• Swapping in as a PSR-18 client for libraries (like league/oauth2-client or API SDKs) that only depend on the PSR interface

Under The Hood

Architecture: The component centers on a single HttpClientInterface with two production backends selected at runtime — CurlHttpClient (preferred, using native cURL multi-handles for HTTP/2 multiplexing and concurrency) and NativeHttpClient (a pure-PHP stream-based fallback). Responses are lazy: ResponseInterface implementations only block on getContent()/getStatusCode(), letting many requests run concurrently and be awaited individually. A decorator chain (RetryableHttpClient, CachingHttpClient, ThrottlingHttpClient, TraceableHttpClient, ScopingHttpClient) wraps the base client to compose cross-cutting behavior without touching core transport code.

Tech Stack: Pure PHP 8.4+, zero mandatory runtime dependencies beyond psr/log and Symfony’s own contracts packages; optional integrations include amphp/http-client, Guzzle, and PSR-7 implementations (nyholm/psr7) for interoperability testing. Build/test tooling uses PHPUnit via phpunit.xml.dist.

Code Quality: The Tests/ directory contains 22+ test files covering the curl, native, mock, retry, caching, and PSR-18 decorators individually, with a shared HttpClientTestCase base exercising common contract behavior across backends. Naming is consistent (*HttpClient, *Trait for shared decorator logic), and exceptions are modeled as a dedicated Exception namespace rather than generic \Exception throws.

API Design: The public surface is intentionally small — request(), stream(), and a handful of options arrays — which keeps the learning curve low despite the component’s internal complexity. PSR-18 and HTTPlug adapter classes mean existing PSR-consuming code needs no changes to swap in this client, a strong developer-experience win for library authors.