gadwinn / psr-http-client
PSR-18 HTTP client with a cURL handler; PSR-17 factories are injected.
Requires
- php: >=8.3
- ext-curl: *
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.1 || ^2.0
Requires (Dev)
- phpdocumentor/shim: *
- phpstan/phpstan: *
- phpunit/phpunit: *
- povils/phpmnd: *
- roave/security-advisories: dev-latest@dev
- squizlabs/php_codesniffer: *
Suggests
- gadwinn/psr-http-message: PSR-7 / PSR-17 implementation
Provides
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 11:22:37 UTC
README
A lightweight PSR-18 HTTP client built on ext-curl. The PSR-17 factories are injected, so it works with any PSR-7 implementation.
Tech Stack
- PHP 8.3+ with ext-curl
- PSR-18 (
psr/http-client: ^1.0) —ClientInterface - PSR-7 / PSR-17 (
psr/http-message,psr/http-factory) — interfaces only; bring your own implementation (e.g.gadwinn/psr-http-message)
Installation
composer require gadwinn/psr-http-client
Usage
Instantiation
use G\Http\Client\Client; use G\Http\Message\{RequestFactory, ResponseFactory, StreamFactory}; // or any PSR-17 factories $client = new Client( responseFactory: new ResponseFactory(), requestFactory: new RequestFactory(), streamFactory: new StreamFactory(), );
The constructor signature:
public function __construct( ResponseFactoryInterface $responseFactory, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, HandlerInterface $handler = new CurlHandler() )
Sending a PSR-7 request
$request = (new RequestFactory()) ->createRequest('GET', 'https://api.example.com/users/42') ->withHeader('Accept', 'application/json'); $response = $client->sendRequest($request); $response->getStatusCode(); // 200 (string) $response->getBody(); // '{"id":42,...}'
Shortcuts
request() builds the request for you; get(), post(), put(), patch(), delete(), head(), options(), connect() and trace() call it with their method.
$response = $client->get('https://api.example.com/users'); $response = $client->post('https://api.example.com/users', [ 'headers' => ['Content-Type' => 'application/json'], 'body' => json_encode(['name' => 'Alice']), ]);
| Option | Type | Effect |
|---|---|---|
headers |
array<string, string|string[]> |
Request headers |
body |
string|StreamInterface |
Request body |
protocolVersion |
string |
1.0, 1.1, 2 or 3 |
requestTarget |
string |
Overrides the path and query of the URI |
Errors
As required by PSR-18, an HTTP error status is not an exception: a 404 or a 500 is returned as a normal response. Exceptions are only thrown when no response could be obtained:
| Exception | Implements | When |
|---|---|---|
G\Http\Client\Exception\RequestException |
RequestExceptionInterface |
The request is invalid (malformed URL, scheme other than http/https) |
G\Http\Client\Exception\NetworkException |
NetworkExceptionInterface |
Network failure: DNS, connection, TLS, timeout… |
G\Http\Client\Exception\ClientException |
ClientExceptionInterface |
Parent of both; also thrown when the response cannot be parsed |
Every exception gives the request back with getRequest(); the code and message are those of cURL.
use Psr\Http\Client\{ClientExceptionInterface, NetworkExceptionInterface}; try { $response = $client->get('https://api.example.com/users'); } catch (NetworkExceptionInterface $e) { // retry later } catch (ClientExceptionInterface $e) { // invalid request or unreadable response }
Behaviour
- Redirects are never followed: a
3xxresponse is returned as is, with itsLocationheader. - Interim
1xxresponses are dropped; only the final response is returned. - Repeated response headers (
Set-Cookie…) are all kept. - When the request has a body and no
Content-Type, cURL addsContent-Type: application/x-www-form-urlencoded. - The cURL handle is kept between requests, so connections are reused.
cURL options
Pass extra cURL options to the handler: timeouts, proxy, CA bundle, user agent…
use G\Http\Client\Handler\CurlHandler; $handler = new CurlHandler([ CURLOPT_CONNECTTIMEOUT => 5, // default: 60 CURLOPT_TIMEOUT => 30, // default: none CURLOPT_PROXY => 'http://proxy.local:3128', CURLOPT_USERAGENT => 'my-app/1.0', ]); $client = new Client(new ResponseFactory(), new RequestFactory(), new StreamFactory(), $handler);
The options the handler needs to build the response cannot be overridden: URL, method, headers, body, HTTP version, header/body callbacks and CURLOPT_FOLLOWLOCATION.
Custom handler
Implement G\Http\Client\Handler\HandlerInterface to replace the transport (another extension, a fake for your tests…). The handler receives the request and an empty response with a writable body, and returns the filled response.
use G\Http\Client\Handler\HandlerInterface; use Psr\Http\Message\{RequestInterface, ResponseInterface}; final class FakeHandler implements HandlerInterface { public function handle(RequestInterface $request, ResponseInterface $response): ResponseInterface { $response->getBody()->write('{"ok":true}'); return $response->withHeader('Content-Type', 'application/json'); } } $client = new Client(new ResponseFactory(), new RequestFactory(), new StreamFactory(), new FakeHandler());
Tests
The functional tests start a local PHP built-in server (tests/Fixtures/server.php); no Internet access is needed.
composer test-all
License
MIT, see LICENSE.