amphp/http-client

Interceptors allow you to compose custom behavior into the HttpClient. You can register them using HttpClientBuilder::intercept().

There are two types of interceptors:

1. ApplicationInterceptor: The standard type used for most logic (e.g., adding headers, caching, retries).
2. NetworkInterceptor: Used when you need access to underlying connection properties like IPs or TLS settings.

Warning: NetworkInterceptor implementations must be highly performant to avoid triggering client timeouts, as they run after the connection is established.

Common Interceptors:

• AddRequestHeader / AddResponseHeader
• RemoveRequestHeader / RemoveResponseHeader
• SetRequestHeader / SetResponseHeader
• RetryRequests
• FollowRedirects
• SetRequestTimeout
• CookieHandler (via amphp/http-client-cookies)
• PrivateCache (via amphp/http-client-cache)

use Amp\Http\Client\HttpClientBuilder;
use Amp\Http\Client\Interceptor\SetRequestHeader;
use Amp\Http\Client\Interceptor\SetResponseHeader;
use Amp\Http\Client\Request;

$client = (new HttpClientBuilder())
    ->intercept(new SetRequestHeader('x-foo', 'bar'))
    ->intercept(new SetResponseHeader('x-tea', 'now'))
    ->build();

$response = $client->request(new Request("https://httpbin.org/get"));

The Response object provides access to the server's response. Like requests, Response objects are mutable.

• Status: Use getStatus() (integer) and getReason() (string) to check the HTTP status.
• Protocol: Use getProtocolVersion() to get the HTTP version.
• Headers: Access headers via hasHeader(), getHeader(), getHeaderArray(), or getHeaders(). The getHeaders() method returns an associative array where keys are header names and values are arrays of strings:

  ["header-1" => ["value-1", "value-2"], "header-2" => ["value-1"]]

• Body: getBody() returns a Payload.
  • Warning: $response->getBody()->read() reads only a single chunk. To get the entire body, use $response->getBody()->buffer().
• Request Context:
  • getRequest(): Returns the request corresponding to the response (may differ from original if redirects occurred).
  • getOriginalRequest(): Returns the initial request sent by the client.
  • getPreviousResponse(): Accesses previous responses in a redirect chain (note: bodies of previous responses are discarded).

$response = $client->request($request);

var_dump($response->getStatus(), $response->getReason());
var_dump($response->getProtocolVersion());
$body = $response->getBody()->buffer();

The Request class is used to define the details of an HTTP request.

Important: Request objects are mutable. If you need to retry a request or use it for sub-requests, you should clone the object to perform a deep clone.

Key capabilities:

• URI: Set via constructor or setUri(string $uri).
• Method: Set via constructor or setMethod(string $method). Defaults to GET.
• Headers:
  • setHeader(string $field, string $value): Replaces existing values for the field.
  • addHeader(string $field, string $value): Adds an additional header line.
  • setHeaders(array $headers): Sets multiple headers at once.
  • getHeader(string $field): Returns the first header value or null.
  • getHeaderArray(string $field): Returns all header values for a field as an array.
• Body: Set via setBody($body). Accepts string, null, or HttpContent. Strings and nulls are automatically converted to HttpContent to ensure the body can be re-sent during redirects or retries.

$request = new Request("https://httpbin.org/post", "POST");
$request->setBody("foobar");
$request->setUri("https://google.com/");
$request->setMethod("PUT");
$request->setHeader("X-Foobar", "Hello World");

The ModifyRequest interceptor allows you to apply transformations to an outgoing Request using a provided mapper closure. This is useful for tasks like adding default headers, modifying URLs, or injecting authentication tokens globally for all requests passing through the interceptor.

The mapper closure must accept a Request and return either a modified Request instance or null. If the closure returns null, the original request is used without modification.

ModifyRequest implements both NetworkInterceptor and ApplicationInterceptor, meaning it can be used at different layers of the HTTP client stack.

use Amp".$
    Http".$
    Client".$
    Interceptor".$
    ModifyRequest;
use Amp".$
    Http".$
    Client".$
    Request;

// Example: An interceptor that adds a custom User-Agent header to every request
$userAgentInterceptor = new ModifyRequest(function (Request $request): Request {
    return $request->withHeader('User-Agent', 'MyCustomApp/1.0');
});

// This interceptor can then be added to your HttpClient stack