Download the PHP package thingston/psr18 without Composer

thingston/psr18

Implementation of PSR-18 standard for sending HTTP requests and receiving HTTP responses.

Requirements

• PHP 8.5 or newer
• PHP cURL extension

Installation

Quick start

Configuration

Client accepts optional named parameters for every concern. All policy parameters default to null (disabled):

Redirect policy

Controls whether and how the client follows HTTP redirects. By default the client does not follow redirects unless a RedirectPolicy is provided.

RedirectPolicy::resolveLocation(string $location, RequestInterface $request): string is a utility for resolving relative Location header values when handling redirects manually.

Retry policy

Retries are opt-in and default to idempotent methods only (GET, HEAD, OPTIONS, PUT, DELETE, TRACE). The default failure set retries common transient cURL errors and HTTP 408, 425, 429, 500, 502, 503, 504.

When the server returns a Retry-After header on a retryable response, the client honours it (capped at 60 s) instead of using the computed delay.

TLS policy

Groups SSL/TLS configuration into a named object rather than raw cURL option arrays.

Timeout policy

Separates connection timeout from transfer timeout.

TimeoutPolicy takes precedence over any equivalent options set in RequestOptions.

Auth policy

Handles Basic, Bearer, and Digest authentication without manually building Authorization headers.

Basic and Bearer auth inject an Authorization header. Digest auth uses curl's native challenge-response mechanism via CURLOPT_HTTPAUTH.

Proxy options

Concurrent requests

MultiClient wraps curl_multi_* and sends multiple requests in parallel. It accepts the same policy parameters as Client except retryPolicy, circuitBreaker, logger, and middleware.

Cookie jar

Persists session cookies across requests using CURLOPT_COOKIEFILE and CURLOPT_COOKIEJAR. A temporary file is created automatically when no path is given and deleted on destruction.

CookieJar::getPath(): string returns the underlying file path. CookieJar::clear(): void truncates the file, discarding all stored cookies without changing the path.

Circuit breaker

Opens the circuit after a configurable number of consecutive failures and throws immediately — without attempting the request — until the reset timeout elapses.

States: closed (normal) → open (blocking) → half-open (probe allowed) → closed.

Middleware

A MiddlewareInterface pipeline wraps sendRequest() with cross-cutting behaviour. Middleware runs in registration order (first registered = outermost wrapper).

PSR-3 logging

Inject any Psr\Log\LoggerInterface to receive structured log entries for requests, responses, retries, and errors. Zero-cost when no logger is injected.

Log levels: debug for normal request/response, warning for retries and failures.

Raw cURL options

For anything not covered by a policy, pass raw cURL options via RequestOptions or ResponseOptions. Reserved options (those the client manages internally) are rejected at construction time.

RequestOptions constants: USER_AGENT, CONNECT_TIMEOUT, TIMEOUT, FOLLOW_LOCATION, MAX_REDIRECTS.

RequestOptions ships with defaults applied to every request: USER_AGENT = 'thingston/http-client' and CONNECT_TIMEOUT = 10 (seconds). These can be overridden via RequestOptions or superseded by the corresponding policy object.

Notes

• The request URI must be absolute and include a host.
• HTTP/1.0, HTTP/1.1, HTTP/2, and HTTP/3 are supported when the installed cURL build supports it.
• Policy options (redirect, TLS, proxy, timeout, auth, cookie jar) always override any equivalent raw options set in RequestOptions.
• RetryPolicy only retries idempotent methods by default; POST and PATCH are excluded unless explicitly added to the methods list.