Download the PHP package dormilich/http-client without Composer

HTTP client request/response handlers

The purpose of this library is to define handlers around a PSR-18 HTTP client that convert data into a request and a response back into the desired data structure, while being independent of the actual HTTP client implementation.

Installation

You can install this library via composer:

To use this library, install you personal choice of a PSR-18 HTTP client and PSR-17 HTTP factories.

HTTP Client

The HTTP client needs to be set up with a PSR-18 HTTP client and a PSR-17 request and stream factory.

While this may look tedious for manual setup, this becomes easy in most frameworks with dependency injection.

Before sending off the request, the client will apply any default headers that were defined as well as any request modifications (see Request modification).

If no data transformer is defined (see Data transformers), it is only possible to send PSR-7 requests. Otherwise, the client will complain that no encoder is defined for the data to be processed and throw a UnsupportedDataTypeException.

The client supports the most common HTTP methods as shorthand methods. This requires data encoders to be defined previously.

One-time headers and other request methods can be submitted using the fetch() method.

Note: For requests that do not have a request body (GET, HEAD) the data will be put into the query string. As there is no formal definition of the structure of the query string, the format of the applied data encoder is used.

Data transformers

Data transformers allow arbitrary data to be converted into a PSR-7 request and a PSR-7 response back into a specific data structure. For this purpose, several data transformers are predefined.

Data transformers implementing TransformerInterface can encode the request and decode the response.

Data transformers implementing DataEncoderInterface can encode the request but ignore the response.

Data transformers implementing DataDecoderInterface can decode the response but ignore the request. These transformers are set up to only decode successful responses.

If you need to decode an error response, you can wrap the transformer into a Decoder object and add the status restriction using a status matcher instance.

Should multiple data transformers encode the same data type or process the same response type, the first one defined wins.

The transformers for handling JSON and URL-encoded data have been split into encoders and decoders to allow the response to be decoded independently of the request encoder (e.g. when you want to decode a JSON response into a specific object).

JSON transformers

The JsonDecoder and JsonEncoder accept any JSON_* constants for encoding and decoding as constructor argument.

Note: Be aware that JSON_NUMERIC_CHECK will decode any integer string above PHP_INT_MAX into a floating point number. It will also convert numeric strings that may not be intended for conversion (e.g. phone numbers, postal codes, etc.).

URL transformers

These transformers url-encode/url-decode data. By default, this uses the PHP-style of parsing. There is another parser available that strictly parses key-value pairs (i.e. no nested arrays).

Request modification

Despite encoding data for the request, encoders can also be used for modifying the request. Therefore, the encoder must support Psr\Http\Message\RequestInterface as payload data type in the encoder's supports() method.

An example where this is useful are encoders that modify the request, e.g. adding headers.

Parsing the response

The response can be processed by defining response decoders or data decoders. Data decoders will only be used on successful responses while response decoders can be configured to process any (specific) response.

In contrast to encoders, the client does not need to have decoders defined, it will return the response body content if no decoder matches (or exists).

Exceptions

Beside the aforementioned UnsupportedDataTypeException that indicates a setup issue, the client can also throw a RequestException. The PSR-18 exceptions are wrapped into a RequestException and failures to encode or decode will throw an EncoderException or DecoderException, respectively.