edgetelemetrics / reactphp-http-browser-curl

v0.5.0 2026-09-11 11:46 UTC

Requires

• php: ^8.2
• ext-curl: *
• evenement/evenement: ^3.0
• fig/http-message-util: ^1.1
• guzzlehttp/psr7: ^2.6
• psr/http-client: ^1.0.3
• psr/http-message: ^1.0.1
• react/async: ^4 || ^3 || ^2
• react/event-loop: ^1.2
• react/http: ^v1.11
• react/promise: ^3 || ^2
• react/stream: ^1.4

Requires (Dev)

• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^9.5
• react/dns: *
• react/promise-stream: ^1.4
• react/promise-timer: ^1.9

MIT

• James Lucas

Published on Packagist.org on 2026-09-11 11:49 UTC

README

Implementation of an Async HTTP client using CURL.

Why not use package react/http Browser?

Using cURL allows for HTTP/2+3, connection pooling (with keep-alive), and the extraction of timing data for the requests. This functionality is not available though the ReactPHP Browser implementation

Requirements

The package is compatible with PHP 8.2+ and requires the cURL extension and react/event-loop library.

Installation

You can add the library as project dependency using Composer:

composer require edgetelemetrics/reactphp-http-browser-curl

Examples

See /examples directory. Examples based on examples from reactphp/http under MIT License

Timing

Request timing values are returned in the PSR7 Response object headers under the key Server-Timing

Configuration

The Browser can be configured with standard CURLOPT_* parameters given via the constructor.

$browser = new Browser([
    CURLOPT_TIMEOUT => 20,
    CURLOPT_DOH_URL => 'https://1.1.1.1/dns-query',
    CURLOPT_DNS_SERVERS => '1.1.1.1',
]);

Request methods

get(), head(), post(), put(), patch(), delete() and options() are provided as convenience methods. request($method, $url, $headers, $body) and requestStreaming() accept any valid HTTP method: TRACE, QUERY, WebDAV methods such as PROPFIND/MKCOL, and any other RFC 7230 token, all sent verbatim. HEAD and TRACE never send a request body (RFC 9110). CONNECT is rejected with an InvalidArgumentException, as it creates a tunnel rather than a request/response exchange.

The Browser also implements PSR-18 Psr\Http\Client\ClientInterface, so it can be used where a synchronous PSR-18 client is expected:

$request = new GuzzleHttp\Psr7\Request('QUERY', $url, [], $body);
$response = $browser->sendRequest($request); // blocks by driving the event loop

Transport failures throw EdgeTelemetrics\React\Http\Io\NetworkException and invalid requests throw EdgeTelemetrics\React\Http\Io\RequestException; 4xx/5xx responses are returned rather than thrown.

Security

Only http:// and https:// request URLs are accepted; any other scheme is rejected with an InvalidArgumentException. As a defence in depth, CURLOPT_PROTOCOLS and CURLOPT_REDIR_PROTOCOLS default to CURLPROTO_HTTP | CURLPROTO_HTTPS, so redirects to schemes such as file:// are blocked as well. Passing your own CURLOPT_PROTOCOLS / CURLOPT_REDIR_PROTOCOLS to the constructor overrides the cURL-level restriction (the request URL itself must still be HTTP(S)).

withBase() is a convenience for resolving relative URLs, not a host allow-list: absolute and protocol-relative URLs replace the base entirely (matching react/http). Allow-list hosts yourself if request URLs can come from untrusted input.

$browser->withSsrfProtection() rejects requests that connect to a non-public address (loopback, RFC 1918, link-local, CGNAT, multicast, unique-local IPv6, and IPv4-mapped IPv6 addresses). The check uses CURLOPT_PREREQFUNCTION and runs after the connection is established but before any request is sent, on every connection and every redirect hop, so DNS rebinding and obfuscated IP literals (127.1, decimal/hex forms) cannot bypass it. It is disabled by default and requires PHP 8.4+; enabling it on older PHP throws a RuntimeException rather than silently doing nothing. Note that the TCP/TLS handshake still happens before the check, and a configured proxy is not inspected (the proxy's address is checked instead).

$browser = (new Browser())->withSsrfProtection();

Timeouts

Requests use PHP's default_socket_timeout (60 seconds by default) when no explicit timeout is set. Use $browser->withTimeout(5) for a custom value, $browser->withTimeout(true) to re-enable the default, or $browser->withTimeout(false) to disable timeouts entirely. A CURLOPT_TIMEOUT / CURLOPT_TIMEOUT_MS passed to the constructor takes precedence over the default.

Response compression

Response bodies are returned exactly as sent; no Accept-Encoding header is sent by default. To let cURL negotiate and transparently decode compressed responses, pass CURLOPT_ACCEPT_ENCODING in the constructor:

$browser = new Browser([CURLOPT_ACCEPT_ENCODING => '']);

Note that cURL decodes the body but the response headers still describe the compressed wire format (Content-Encoding, Content-Length), so the Content-Length header and the streaming body's getSize() may not match the decoded body length.

Connection Reuse

Each instance of Browser shares a Connection pool, DNS cache, SSL cache, and Cookie Jar. An example of this can be seen in /examples/connection_pooling.php script.

Connection Metadata

Connection Timing

The request/response timing is provided though the header 'ServerTiming' in the Response object.

Each timing point is defined as <timing point>;dur=<duration in second>

• namelookup_time
• connect_time
• appconnect_time
• pretransfer_time
• redirect_time
• starttransfer_time
• total_time

Connection Details

Additional request/response metadata is provided though the header 'X-Connection' in the Response object.

Key/Value pairs are as follows:

• effective_url=<final url after any redirects>
• connection;count=<number of connections opened during the request, 0 if existing connection reused>
• redirect;count=<number of redirects followed>
• upload;size=<bytes sent in request(headers+body) including redirects>;speed=<overall bytes per second upload>
• download;size=<bytes received in response(headers+body) including redirects>;speed=<overall bytes per second download>

License

MIT, see LICENSE file.

Contributing

Bug reports (and small patches) can be submitted via the issue tracker. Forking the repository and submitting a Pull Request is preferred for substantial patches.