README

HTTP client wrapper with automatic retries, exponential backoff, jitter, circuit breaker, and request logging.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/http-retry-client

Usage

Basic Usage

Implement the HttpExecutor interface to wrap your preferred HTTP client:

use PhilipRehberger\HttpRetry\Contracts\HttpExecutor;
use PhilipRehberger\HttpRetry\HttpRequest;
use PhilipRehberger\HttpRetry\HttpResponse;
use PhilipRehberger\HttpRetry\RetryClient;

class CurlExecutor implements HttpExecutor
{
    public function execute(HttpRequest $request): HttpResponse
    {
        $ch = curl_init($request->url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $request->method);

        if ($request->body !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, $request->body);
        }

        $body = curl_exec($ch);
        $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return new HttpResponse($statusCode, $body);
    }
}

$client = new RetryClient(new CurlExecutor());
$result = $client->send(new HttpRequest('GET', 'https://api.example.com/data'));

if ($result->successful()) {
    echo $result->body;
}

Custom Retry Policy

use PhilipRehberger\HttpRetry\RetryClient;
use PhilipRehberger\HttpRetry\RetryPolicy;

$policy = new RetryPolicy(
    maxRetries: 5,
    baseDelayMs: 200,
    maxDelayMs: 30000,
    multiplier: 2.0,
    jitter: true,
    retryableStatusCodes: [429, 500, 502, 503, 504],
);

$client = new RetryClient($executor, $policy);

Fluent Builder

use PhilipRehberger\HttpRetry\RetryPolicy;

$policy = RetryPolicy::builder()
    ->maxRetries(5)
    ->baseDelay(200)
    ->maxDelay(30000)
    ->multiplier(3.0)
    ->withoutJitter()
    ->retryOn([500, 502, 503])
    ->build();

Handling Retry Results

use PhilipRehberger\HttpRetry\Exceptions\MaxRetriesExceededException;

try {
    $result = $client->send($request);

    echo "Status: {$result->statusCode}\n";
    echo "Attempts: {$result->attempts}\n";
    echo "Total delay: {$result->totalDelayMs}ms\n";
    echo "Was retried: " . ($result->wasRetried ? 'yes' : 'no') . "\n";
} catch (MaxRetriesExceededException $e) {
    echo "Failed after {$e->attempts} attempts: {$e->getMessage()}\n";
}

Jitter Modes

Control the jitter algorithm used for backoff delays:

use PhilipRehberger\HttpRetry\JitterMode;
use PhilipRehberger\HttpRetry\RetryPolicy;

// Full jitter (default): rand(0, delay)
$policy = RetryPolicy::builder()
    ->jitterMode(JitterMode::Full)
    ->build();

// Equal jitter: delay/2 + rand(0, delay/2)
$policy = RetryPolicy::builder()
    ->jitterMode(JitterMode::Equal)
    ->build();

// Decorrelated jitter: rand(base, previous * 3)
$policy = RetryPolicy::builder()
    ->jitterMode(JitterMode::Decorrelated)
    ->build();

Retry Hooks

Register callbacks that run before and after each retry attempt:

use PhilipRehberger\HttpRetry\RetryPolicy;

$policy = RetryPolicy::builder()
    ->beforeRetry(function (int $attempt, ?\Throwable $error): void {
        echo "Retrying attempt {$attempt}...\n";
    })
    ->afterRetry(function (int $attempt, ?\Throwable $error): void {
        if ($error !== null) {
            echo "Attempt {$attempt} failed: {$error->getMessage()}\n";
        }
    })
    ->build();

Custom Retryable Status Codes

$policy = RetryPolicy::builder()
    ->retryOn([408, 429, 500, 502, 503, 504])
    ->build();

Circuit Breaker

Protect downstream services with a circuit breaker that opens after consecutive failures:

use PhilipRehberger\HttpRetry\CircuitBreakerWrapper;
use PhilipRehberger\HttpRetry\Exceptions\CircuitBreakerOpenException;

$breaker = new CircuitBreakerWrapper(failureThreshold: 5, recoveryTimeoutSeconds: 30);

try {
    $result = $breaker->execute(fn () => $client->send($request));
} catch (CircuitBreakerOpenException $e) {
    // Circuit is open, requests are being rejected
}

// Or configure via the builder
$builder = RetryPolicy::builder()
    ->withCircuitBreaker(failureThreshold: 5, recoveryTimeout: 30);

The circuit breaker transitions through three states:

• Closed: Requests flow normally; failures are counted
• Open: Requests are rejected immediately with CircuitBreakerOpenException
• Half-Open: After the recovery timeout, one request is allowed through to test recovery

Request Logging

Log HTTP requests, responses, and failures for observability:

use PhilipRehberger\HttpRetry\RequestLogger;

$logger = new RequestLogger(function (array $entry): void {
    // $entry contains: event, method, url, attempt, status_code, duration_ms, error, etc.
    error_log(json_encode($entry));
}, logBodies: true);

$logger->logRequest($request, attempt: 1);
$logger->logResponse($response, attempt: 1, durationMs: 42.5);
$logger->logFailure($exception, attempt: 1);

// Or configure via the builder
$builder = RetryPolicy::builder()
    ->withLogger(fn (array $entry) => error_log(json_encode($entry)), logBodies: false);

Timeout Configuration

Set connection and request timeouts:

$policy = RetryPolicy::builder()
    ->connectionTimeout(5000)  // 5 seconds
    ->requestTimeout(30000)    // 30 seconds
    ->build();

// Timeouts can also be set per-request
$request = new HttpRequest(
    method: 'GET',
    url: 'https://api.example.com/data',
    connectionTimeoutMs: 3000,
    requestTimeoutMs: 15000,
);

API

RetryPolicy

RetryPolicyBuilder

RetryClient

RetryResult

HttpExecutor (Interface)

CircuitBreakerWrapper

RequestLogger

MaxRetriesExceededException

CircuitBreakerOpenException

Thrown when a request is rejected because the circuit breaker is in the open state.

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT