Skip to main content

​
Overview

The RetryPolicy class configures retry behavior for job execution. It defines timeout limits, maximum retry attempts, and delay between retries. Each job has a default retry policy that can be customized using withRetry().

​
Class signature

final class RetryPolicy implements RetryPolicyInterface
Implements: Chevere\Workflow\Interfaces\RetryPolicyInterface Location: src/RetryPolicy.php:20

​
Constructor

public function __construct(
    int $timeout = 0,
    int $maxAttempts = 1,
    int $delay = 0
)
​
$timeout
int<0, max>
default:"0"
Maximum execution time in seconds across all attempts. A value of 0 indicates no timeout limit.
​
$maxAttempts
int<1, max>
default:"1"
Maximum number of execution attempts. This includes the initial attempt. For example, a value of 3 means one initial attempt plus two retries. Minimum value is 1.
​
$delay
int<0, max>
default:"0"
Delay between retry attempts in seconds. Applied before each subsequent attempt (not before the initial attempt). A value of 0 means immediate retry.
Example: 
use Chevere\Workflow\RetryPolicy;

// No retries (default)
$noRetry = new RetryPolicy();

// Retry up to 3 times with 5 second delay
$basicRetry = new RetryPolicy(
    timeout: 30,
    maxAttempts: 3,
    delay: 5
);

// Unlimited timeout with exponential backoff handled externally
$unlimitedRetry = new RetryPolicy(
    timeout: 0,        // No timeout
    maxAttempts: 5,    // Try 5 times
    delay: 0           // No automatic delay
);

​
Public methods

​
timeout()

Returns the maximum execution time in seconds. 
public function timeout(): int
​
return
int<0, max>
Timeout in seconds. Returns 0 if no timeout limit is set.
Location: src/RetryPolicy.php:38 Description: The job fails when this timeout is exceeded, regardless of remaining attempts. This timeout applies to the total execution time across all retry attempts, not to individual attempts. Example: 
$policy = new RetryPolicy(timeout: 60, maxAttempts: 3);
echo $policy->timeout(); // 60

// The job will fail if total execution time exceeds 60 seconds,
// even if there are retry attempts remaining

​
maxAttempts()

Returns the maximum number of execution attempts. 
public function maxAttempts(): int
​
return
positive-int
Number of attempts (minimum 1).
Location: src/RetryPolicy.php:43 Description: This includes the initial attempt. For example, a value of 3 means one initial attempt plus two retries. Example: 
$policy = new RetryPolicy(maxAttempts: 3);
echo $policy->maxAttempts(); // 3

// Execution flow:
// Attempt 1 (initial) -> fails
// Attempt 2 (retry 1) -> fails
// Attempt 3 (retry 2) -> succeeds or final failure

​
delay()

Returns the delay between retry attempts in seconds. 
public function delay(): int
​
return
int<0, max>
Delay in seconds. Returns 0 if no delay is configured.
Location: src/RetryPolicy.php:48 Description: Applied before each subsequent attempt (not before the initial attempt). A value of 0 means immediate retry with no waiting period. Example: 
$policy = new RetryPolicy(maxAttempts: 3, delay: 5);
echo $policy->delay(); // 5

// Execution timeline:
// t=0s:  Attempt 1 fails
// t=5s:  Attempt 2 (after 5s delay)
// t=10s: Attempt 3 (after another 5s delay)

​
Usage with jobs

Retry policies are typically configured on jobs using the withRetry() method: 
use function Chevere\Workflow\sync;

// Create a job with retry policy
$job = sync(new ApiCallAction())
    ->withRetry(
        timeout: 30,      // Total timeout: 30 seconds
        maxAttempts: 3,   // Try up to 3 times
        delay: 5          // Wait 5 seconds between retries
    );

// Access the retry policy
$policy = $job->retryPolicy();
echo $policy->timeout();      // 30
echo $policy->maxAttempts();  // 3
echo $policy->delay();        // 5

​
Common patterns

​
No retry (default)

// Default: single attempt, no timeout, no delay
$policy = new RetryPolicy();

$job = sync(new SimpleAction());
// Uses default RetryPolicy(timeout: 0, maxAttempts: 1, delay: 0)

​
Quick retries for transient failures

// Retry immediately for network glitches
$job = sync(new NetworkAction())
    ->withRetry(
        timeout: 10,      // Fail after 10 seconds total
        maxAttempts: 3,   // Try 3 times
        delay: 0          // No delay (immediate retry)
    );

​
Retry with backoff

// Allow time for external service recovery
$job = sync(new ExternalApiAction())
    ->withRetry(
        timeout: 60,      // 60 second total timeout
        maxAttempts: 4,   // 4 attempts (1 initial + 3 retries)
        delay: 10         // 10 second delay between attempts
    );

​
Persistent retry with no timeout

// Keep trying until success (use with caution)
$job = sync(new EventuallyConsistentAction())
    ->withRetry(
        timeout: 0,       // No timeout
        maxAttempts: 10,  // Try up to 10 times
        delay: 30         // 30 seconds between attempts
    );

​
Validation

The constructor validates parameters using Chevere Parameter attributes:
  • $timeout must be >= 0
  • $maxAttempts must be >= 1
  • $delay must be >= 0
Invalid values will throw an exception: 
// This will throw an exception
try {
    $invalid = new RetryPolicy(
        timeout: -1,      // ❌ Invalid: must be >= 0
        maxAttempts: 0,   // ❌ Invalid: must be >= 1
        delay: -5         // ❌ Invalid: must be >= 0
    );
} catch (\Exception $e) {
    // Parameter validation failed
}

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us