Weave Code
Http Client Contracts Laravel Package
symfony/http-client-contracts
Symfony HttpClient Contracts provides stable interfaces for HTTP clients and responses, extracted from Symfony. Build libraries against these battle-tested abstractions and swap implementations easily while staying compatible with Symfony’s HttpClient ecosystem.
Generic abstractions related to HTTP clients
Frequently asked questions about Http Client Contracts
- What is symfony/http-client-contracts used for?
- It is a set of generic abstractions extracted from Symfony that defines interfaces for HTTP clients and responses. The package contains no concrete client implementation, so it is used to type-hint dependencies such as HttpClientInterface in libraries, SDKs, and services. In Laravel, it helps decouple application code from a specific HTTP client so implementations can be swapped more easily.
- How do I install symfony/http-client-contracts in a Laravel app?
- Install it with Composer using composer require symfony/http-client-contracts. You will also need a concrete implementation such as symfony/http-client or Guzzle with a PSR-18 adapter, because the contracts package alone cannot send requests. After installation, bind HttpClientInterface to your chosen client in a Laravel service provider.
- Is symfony/http-client-contracts a drop-in replacement for Laravel's Http facade?
- No. Laravel's Http facade is a concrete convenience API, while symfony/http-client-contracts provides interfaces that must be injected and bound to an implementation. Adopting it usually requires refactoring direct Http::get calls into services that accept HttpClientInterface. You can keep the facade as a wrapper if you do not want to replace it everywhere at once.
- Which Laravel and PHP versions work with symfony/http-client-contracts?
- Current Symfony contracts are designed for modern PHP versions, with PHP 8.1 or later being the practical baseline according to the package context. Laravel 10 and newer are a natural fit, while Laravel 9 or older apps may need additional bridges or compatibility work. Always check the exact Composer constraints for the contracts version you install.
- How do I bind HttpClientInterface in Laravel's service container?
- Create a service provider binding, for example bind HttpClientInterface::class to a closure that returns Symfony\Component\HttpClient\HttpClient::create(). Then inject HttpClientInterface into your service or SDK constructors instead of calling the Http facade directly. If you prefer Guzzle, bind the interface to a PSR-18 adapter around your Guzzle client. This keeps the implementation swappable and testable.
- How can I test code that depends on HttpClientInterface in Laravel?
- Use Symfony's MockHttpClient or TestHttpClient to return predefined responses without making real network calls. Bind the mock implementation into Laravel's container for the test, then assert that your service handles the response correctly. Mocking the interface is straightforward, but it requires some setup compared with faking Laravel's Http facade.
- What is the difference between symfony/http-client-contracts and symfony/http-client?
- symfony/http-client-contracts contains only the interfaces and abstractions, while symfony/http-client is a full implementation that actually sends HTTP requests. The implementation adds features such as async requests, connection pooling, and HTTP/2 support. Most projects install both: the contracts for type safety and the client for real behavior.
- Is symfony/http-client-contracts PSR-18 compatible?
- It is not the PSR-18 interface itself; PSR-18 defines Psr\Http\Client\ClientInterface. Symfony's contracts align with similar HTTP client concepts and can interoperate through adapters, which helps with Laravel and third-party client compatibility. If your project must enforce PSR-18 specifically, use psr/http-client or an appropriate bridge alongside your chosen client.
- Does symfony/http-client-contracts handle errors, async requests, or connection pooling?
- No. The contracts package only defines interfaces, so error handling, async behavior, and pooling are provided by the concrete client implementation. With Symfony's HttpClient, non-2xx responses throw exceptions by default unless you disable throwing, and async requests require explicit use of AsyncHttpClient. Connection pooling is configured in the implementation layer, not in the contracts.
- Is symfony/http-client-contracts stable and actively maintained?
- Yes. It is part of the Symfony contracts family, extracted from battle-tested Symfony components and used across the Symfony ecosystem. Maintenance follows Symfony's release cycle, and the interfaces are intended to be stable for library authors. In Laravel projects, Laravel-specific adapters or facade integrations may still need updates if the framework's HTTP stack changes.
Weaver
How can I help you explore Laravel packages today?