README

A lightweight, resilient HTTP transport client built on top of Guzzle. It provides a clean interface for HTTP requests, pluggable response-reading strategies, and traffic logging capabilities.

Features

Factory-based creation: Create clients through HttpTransportClientFactory with safe defaults.
Pluggable Read Strategies: Choose how to read response bodies (buffered, idle-resistant, or idle+deadline).
Traffic Logging: Log requests, responses, and transport errors globally or per request.
Header masking: Sensitive request and response headers are masked before logging.
Resilient Error Handling: Domain-specific exceptions for connection issues and HTTP errors.

Installation

Requires PHP >= 8.3 and Guzzle 7 or 8.

composer require adachsoft/http-transport

Basic Usage

use AdachSoft\HttpTransport\Dto\HttpRequestDto;
use AdachSoft\HttpTransport\HttpTransportClientFactory;
use AdachSoft\HttpTransport\ReadStrategy\BufferedResponseReadStrategy;
use GuzzleHttp\Client;

$guzzleClient = new Client();
$transportFactory = new HttpTransportClientFactory();
$transportClient = $transportFactory->createDefault($guzzleClient);

$requestDto = new HttpRequestDto('GET', 'https://api.example.com/data');
$response = $transportClient->send($requestDto, new BufferedResponseReadStrategy());

echo $response->body;

Logging and request correlation

You can provide a custom logger globally through the factory or per request in send(...).

use AdachSoft\HttpTransport\Dto\HttpRequestDto;

$requestDto = new HttpRequestDto(
    method: 'POST',
    uri: 'https://api.example.com/orders',
    headers: ['Authorization' => 'Bearer token-value'],
    jsonBody: ['productId' => 123],
    requestId: 'order-123',
);

$response = $transportClient->send($requestDto, new BufferedResponseReadStrategy(), $perRequestLogger);

When requestId is not provided, the client generates one automatically. Logged headers are masked by default.

Response Read Strategies

BufferedResponseReadStrategy: Reads the entire response body into memory at once. Suitable for small to medium-sized responses.
IdleResistantResponseReadStrategy: Reads body in chunks with idle timeout enforcement between chunks.
IdleAndDeadlineResponseReadStrategy: Reads in chunks and enforces both idle timeout between chunks and total read deadline.

Example with idle and total limits:

use AdachSoft\HttpTransport\ReadStrategy\IdleAndDeadlineResponseReadStrategy;

$strategy = new IdleAndDeadlineResponseReadStrategy(
    perChunkIdleTimeoutSeconds: 3,
    totalTimeoutSeconds: 20,
);

$response = $transportClient->send($requestDto, $strategy);

Header masking

The default masking hides values for sensitive headers such as Authorization, X-API-Key, and cookies. If needed, provide your own masker implementation through HttpTransportClientFactory::create(...).

Error Handling

The library throws domain-specific exceptions:

TransportConnectionException: Thrown for connection issues, timeouts, or read-strategy timeout violations.
TransportHttpErrorException: Thrown for HTTP error status codes (4xx/5xx), containing the full response body.

Running Tests

composer install
vendor/bin/phpunit

The project also includes static analysis and code quality tools:

vendor/bin/phpstan analyse src tests
vendor/bin/rector process src tests
vendor/bin/php-cs-fixer fix

License

This library is open-sourced software licensed under the MIT license.

adachsoft / http-transport

Maintainers

Package info

Statistics

Security