Download the PHP package amashukov/http-client-php without Composer

amashukov/http-client-php

Tiny zero-dependency PSR-18 HTTP client backed by ext-curl, with a retry / header-injection middleware pipeline.

A small PSR-18 HTTP client backed by ext-curl, with a composable middleware pipeline (retry on selected status codes, header injection). It speaks PSR-7 requests + responses end-to-end and consumes PSR-17 factories, so any PSR-7 implementation (nyholm/psr7, guzzlehttp/psr7, slim/psr7, …) plugs in as the message layer. The package does not ship its own PSR-7 implementation — bring whichever you already use.

Features

• PSR-18 ClientInterface over ext-curl — drop-in anywhere a PSR-18 client is expected.
• Composable middleware Pipeline (itself a PSR-18 client).
• RetryMiddleware — exponential backoff on configurable status codes and network errors.
• HeaderInjectionMiddleware — stamp API keys / User-Agent / telemetry headers on every request.
• Network failures surface as a PSR-18 NetworkExceptionInterface carrying the failed request.
• PSR-7 / PSR-17 consumed via interfaces — bring your own implementation.
• PHPStan level 9 clean, strict_types, final classes.

Why amashukov/http-client-php

Guzzle is excellent but heavy — it pulls in guzzlehttp/psr7, guzzlehttp/promises, and its own promise/handler machinery. When all you need is a PSR-18 client that does retries and header injection, this package is a tiny, zero-runtime-dependency alternative: just ext-curl plus the PSR interface packages. You supply the PSR-7 implementation you already have, so there is no duplicate message library in your dependency tree.

Installation

(Substitute nyholm/psr7 for the PSR-7 implementation of your choice.)

Usage

Send a request

CurlClient implements Psr\Http\Client\ClientInterface; it is a drop-in replacement anywhere a PSR-18 client is expected. The constructor takes a Psr\Http\Message\ResponseFactoryInterface and a Psr\Http\Message\StreamFactoryInterface so the caller controls which PSR-7 implementation backs the returned ResponseInterface.

Network failures (DNS, connect timeout, TLS handshake, …) surface as Amashukov\HttpClient\Exception\TransportException, which implements Psr\Http\Client\NetworkExceptionInterface (and therefore ClientExceptionInterface); getRequest() returns the request that failed.

Add middlewares

Pipeline wraps any PSR-18 client with an ordered list of middlewares, and is itself a PSR-18 client.

Writing your own middleware

Implement Amashukov\HttpClient\MiddlewareInterface:

Call $next($request) exactly once for normal flow, or zero times to short-circuit with a synthetic response.

Built-in middlewares

HeaderInjectionMiddleware — sets the configured headers on every outbound request, replacing any caller-supplied value for the same name. Useful for API keys, User-Agent, telemetry headers.

RetryMiddleware — retries on configured status codes (default [429, 502, 503, 504]) and on any thrown Psr\Http\Client\NetworkExceptionInterface. Delay is exponential (baseDelayMs * 2^(attempt-1)); baseDelayMs=0 means immediate retry. Returns the last response when all attempts are exhausted; rethrows the last network exception when every attempt failed at the transport layer. A $sleeper callable can be injected to control timing in tests.

Requirements

• PHP 8.3+
• ext-curl
• psr/http-client ^1.0
• psr/http-message ^2.0
• psr/http-factory ^1.1
• A PSR-7 implementation (caller-provided)

PSR conformance

• PSR-18 — CurlClient and Pipeline implement Psr\Http\Client\ClientInterface; composer.json declares provide: { psr/http-client-implementation: "1.0" }.
• PSR-7 — every public method exchanges Psr\Http\Message\RequestInterface / ResponseInterface.
• PSR-17 — CurlClient consumes ResponseFactoryInterface + StreamFactoryInterface; it does not implement those factories itself, leaving the choice of PSR-7 implementation to the caller.

Related packages

Quality

• PHPStan level 9.
• php-cs-fixer with the @PER-CS ruleset.
• GitHub Actions CI on every push.
• PSR-18 conformance exercised in the test suite against a PSR-7 implementation.

License

MIT.