README

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

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