HTTPlug: HTTP client abstraction
HTTPlug allows you to write reusable libraries and applications that need an HTTP client without binding to a specific implementation. When all packages used in an application only specify HTTPlug, the application developers can choose the client that best fits their project and use the same client with all packages.
Client Interfaces
HTTPlug defines two HTTP client interfaces that we kept as simple as possible:
PSR-18 defines the
ClientInterface
with asendRequest
method that accepts a PSR-7RequestInterface
and either returns a PSR-7ResponseInterface
or throws an exception that implementsPsr\Http\Client\ClientExceptionInterface
.HTTPlug has the compatible interface
HttpClient
which now extends the PSR-18 interface to allow migrating to PSR-18.HttpAsyncClient
defines asendAsyncRequest
method that sends a PSR-7 request asynchronously and always returns aHttp\Client\Promise
. See Promise for more information.
Implementations
PHP-HTTP offers two types of clients that implement the above interfaces:
Standalone clients that directly implement the interfaces.
Examples: cURL Client and Socket Client (deprecated).
Adapters that wrap existing HTTP clients, such as Guzzle. These adapters act as a bridge between the HTTPlug interfaces and the clients that do not (yet) implement these interfaces.
More and more clients implement PSR-18 directly. If that is all you need, we recommend not using HTTPlug as it would only add overhead. However, as there is no PSR for asynchronous requests yet, you can use the adapters to do such requests without binding yourself to a specific implementation.
Examples: Guzzle 7 Adapter and React Adapter.
Note
Ideally, there will be a PSR for asynchronous requests and all HTTP client libraries out there will implement PSR-18 and the not yet existing PSR. At that point, our adapters will no longer be necessary.
Usage
There are two main use cases for HTTPlug:
Usage in an application that executes HTTP requests (see HTTPlug Tutorial and Framework Integrations);
Usage in a reusable package that executes HTTP requests (see HTTPlug for Library Developers).
History
This project has been started by Eric Geloen as Ivory Http Adapter. It never made it to a stable release, but it relied on PSR-7 which was not stable either that time. Because of the constantly changing PSR-7, Eric had to rewrite the library over and over again (at least the message handling part, which in most cases affected every adapter as well).
In 2015, a decision has been made to move the library to its own organization, so PHP-HTTP was born.
See Migrating to HTTPlug for a guide how to migrate your code from the Ivory adapter.