PHP Retry

Composable retry utility with exponential backoff, jitter, and exception filtering.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/php-retry

Usage

Basic retry

use PhilipRehberger\Retry\Retry;

$result = Retry::times(3)->run(function () {
    return file_get_contents('https://api.example.com/data');
});

echo $result->value;       // The response body
echo $result->attempts;    // Number of attempts made
echo $result->totalTimeMs; // Total time spent in milliseconds

Exponential backoff with jitter

$result = Retry::times(5)
    ->backoff(baseMs: 100, maxMs: 5000)
    ->jitter()
    ->run(fn () => $httpClient->get('/unstable-endpoint'));

Linear backoff

$result = Retry::times(3)
    ->linear(delayMs: 200)
    ->run(fn () => $api->call());

Constant delay

$result = Retry::times(4)
    ->constant(delayMs: 500)
    ->run(fn () => $service->fetch());

Exception filtering

Only retry on specific exceptions:

$result = Retry::times(5)
    ->onlyIf(fn (\Throwable $e) => $e instanceof ConnectionException)
    ->run(fn () => $db->query($sql));

Exclude specific exceptions from retrying:

$result = Retry::times(5)
    ->except(ValidationException::class, AuthenticationException::class)
    ->run(fn () => $api->submit($data));

Conditional Retry

Use shouldRetry() to provide a predicate that receives the exception and attempt number:

$retry = Retry::times(5)
    ->shouldRetry(function (\Throwable $e, int $attempt): bool {
        // Stop retrying after attempt 3 for rate-limit errors
        if ($e instanceof RateLimitException && $attempt >= 3) {
            return false;
        }
        return true;
    })
    ->run(fn () => $api->request());

Use retryOnlyOn() to retry only for specific exception types:

$result = Retry::times(5)
    ->retryOnlyOn(ConnectionException::class, TimeoutException::class)
    ->run(fn () => $httpClient->get('/endpoint'));

Retrieve the total number of attempts after execution with getAttempts():

$retry = Retry::times(5);
$result = $retry->run(fn () => $service->call());

echo $retry->getAttempts(); // e.g. 3

Time budget

Stop retrying after a total time budget is exceeded:

$result = Retry::times(100)
    ->constant(delayMs: 50)
    ->maxDuration(ms: 2000)
    ->run(fn () => $service->call());

Retry forever (with safety)

$result = Retry::forever()
    ->backoff(baseMs: 100, maxMs: 30000)
    ->jitter()
    ->maxDuration(ms: 60000)
    ->run(fn () => $queue->consume());

Callbacks

$result = Retry::times(5)
    ->backoff(baseMs: 100)
    ->beforeRetry(function (int $attempt, \Throwable $e) {
        logger()->warning("Retry attempt {$attempt}: {$e->getMessage()}");
    })
    ->afterRetry(function (int $attempt, ?\Throwable $e) {
        if ($e === null) {
            logger()->info("Succeeded on attempt {$attempt}");
        }
    })
    ->run(fn () => $api->request());

Success callback

$result = Retry::times(5)
    ->backoff(baseMs: 100)
    ->onSuccess(function (RetryResult $r) {
        logger()->info("Succeeded after {$r->attempts} attempt(s)");
    })
    ->run(fn () => $api->request());

Checking retry status

$result = Retry::times(3)->run(fn () => $service->call());

if ($result->wasRetried()) {
    logger()->warning("Operation required retries: {$result->attempts} attempts");
}

echo $result->totalDuration(); // Total elapsed time in milliseconds

API

Method	Description
Retry::times(int $maxAttempts)	Create a retry builder with a maximum number of attempts
Retry::forever()	Create a retry builder that retries indefinitely
->backoff(bool $exponential = true, int $baseMs = 100, int $maxMs = 10000)	Configure exponential (or constant when $exponential = false) backoff
->onTimeout(callable $callback)	Callback invoked with the last exception (or null) when maxDuration is exceeded
->linear(int $delayMs)	Configure linear backoff
->constant(int $delayMs)	Configure constant delay
->jitter(bool $enabled)	Enable or disable jitter
->onlyIf(callable $predicate)	Only retry when predicate returns true
->except(string ...$exceptionClasses)	Exclude specific exception types from retrying
->shouldRetry(callable $predicate)	Predicate receiving exception and attempt number; return false to stop
->retryOnlyOn(string ...$exceptionClasses)	Only retry for the given exception types (sugar for shouldRetry)
->getAttempts()	Get the total number of attempts made after execution
->maxDuration(int $ms)	Set maximum total duration for all attempts
->beforeRetry(callable $callback)	Callback invoked before each retry
->afterRetry(callable $callback)	Callback invoked after each attempt
->onSuccess(callable $callback)	Callback invoked with RetryResult after successful execution
->run(callable $operation)	Execute the operation with retry logic
$result->wasRetried()	Returns true if more than one attempt was made
$result->totalDuration()	Total elapsed time across all attempts in milliseconds

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