Documentation Packages Support

Http Client ⋅ Interceptors

Interceptors allow customizing the HttpClient behavior in a composable fashion without writing another client implementation.

Interceptor use cases range from adding / removing headers from a request / response and recording timing information to more advanced use cases like a fully compliant HTTP cache that intercepts requests and serves them from the cache if possible.


use Amp\Http\Client\Client;
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'))

$response = yield $client->request(new Request(""));

$body = yield $response->getBody()->buffer();

There are two kinds of interceptors with separate interfaces named ApplicationInterceptor and NetworkInterceptor.

Choosing the right interceptor

Most interceptors should be implemented as ApplicationInterceptor. However, there’s sometimes the need to have access to the underlying connection properties. In such a case, a NetworkInterceptor can be implemented to access the used IPs and TLS settings.

Another use-case for implementing a NetworkInterceptor is an interceptor, that should only ever run if the request is sent over the network instead of served from a cache or similar. However, that should usually be solved with the configuration order of the application interceptors.

The big disadvantage of network interceptors is that they have to be rather quick and can’t take too long, because they’re only invoked after the connection has been created and the client will run into a timeout if there’s no activity within a reasonable time.

List of Interceptors

  • AddRequestHeader
  • AddResponseHeader
  • ConditionalInterceptor
  • DecompressResponse
  • FollowRedirects
  • ForbidUriUserInfo
  • IfOrigin
  • ModifyRequest
  • ModifyResponse
  • RemoveRequestHeader
  • RemoveResponseHeader
  • RetryRequests
  • SetRequestHeader
  • SetRequestHeaderIfUnset
  • SetResponseHeader
  • SetResponseHeaderIfUnset
  • CookieHandler
  • PrivateCache