README

Re-play functions that error out!

Some times things not always works at the first attempt. Replay comes in allowing you to plan re-tries and fallbacks strategies for your functions.

Install

composer require gousto/replay

Features

Re-try functions within exception scope
Increase delay for every attempt
Create advanced re-try fallback strategies

Usage

If you want to replay a function when it throws an Exception here is an example:

<?php

use Gousto\Replay\Replay;

try {

    $result = Replay::retry(3, function() {
       return Http::get('example.com'); 
    }, 50);
    
    Log::info("All good");
} catch(\Gousto\Replay\RetryLogicException $e) {
    \Log::error("After 3 times the function still error out!");
}

This code will return you right away the result of Http::get(), if no Exception is occured.

In case of Exception it will retry again up to 3 times with a 50ms interval.

Increase delay at every attempt:

Let's say we want to have a re-try strategy that want to increase the interval at every attempt i.e: 1st attempt 10ms, 2nd attempts 20ms 3rd attempt 40ms

<?php

use Gousto\Replay\Replay;

$replay = Replay::times(3, function() {

    throw new LogicException();
  
}, 10);

$replay->onRetry(function(Exception $e, Replay $replay) {
   $replay->setDelay($replay->getDelay() * 2); 
});

// play the strategy!
$replay->play();

Custom Exceptions

Replay allow you to trigger the retry logic only for particular Exceptions, pass an array of Exceptions class names as 4th paramter:

<?php

use Gousto\Replay\Replay;

// Will throw LogicException and not retry
Replay::retry(3, function() {

    throw new LogicException();
  
}, 0, [RuntimeException::class]);

This will throw a LogicException when the function is invoked. We are going to retry only when the RuntimeException is thrown.

API

- retry($attempts = 1, Closure $user_function, $delay = 0, $exception_targets = [Exception::class])

Return the result of the Closure if no exception is occured. Alternatevely it retries invoking the function until the number of attempts specified. Throw Gousto\Replay\RetryLogicException::class if the number of attempts remained is 0.

$attempts: int, number of attempts the function might be replayed
$user_function: Closure, function which will be replayed if errored
$delay: int, delay is measured in milliseconds
$exception_targets: array, list of exceptions which will be considered as errors

use Gousto\Replay\Replay;

Replay::retry(1, function() {

    throw new Exception();
  
}, 0, [Exception::class]);

- times($attempts = 1, Closure $user_function, $delay = 0, $exception_targets = [])

Helper function for instantiate Replay, facilitate chaining

$attempts: int, number of attempts the function might be replayed
$user_function: Closure, function which will be replayed if errored
$delay: int, delay is measured in milliseconds
$exception_targets: array, list of exceptions which will be considered as errors

use Gousto\Replay\Replay;

$replay = Replay::times(1, function() {

    throw new Exception();
  
}, 0, [Exception::class]);

$replay->play();

play($silent = false):

Tell replay to invoke the function and use the retry logic if needed.

$silent: bool, if true will not throw RetryLogicException but will return it.

use Gousto\Replay\Replay;

$replay = Replay::times(2, function() {

    throw new Exception();
  
}, 0, [Exception::class]);

$result = $replay->play(true); // $result instanceof RetryLogicException

$replay->play(); // throw RetryLogicException

onRetry(Closure $handler):

Hook a function that will be trigger for every attempt, this is useful for logging or any other action.

use Gousto\Replay\Replay;

$counter = 0;
$replay = Replay::times(3, function() use (&$counter) {
    $counter++;
    if ($counter === 3) {
        return $counter;
    }
    throw new Exception("Error"); 
});

// WILL LOG:
// Attempt 1: Failed
// Attempt 2: Failed
$replay->onRetry(function(Exception $exception, Replay $replay) {
   Log::error("Attempt {$replay->attempts()}: Failed"); 
});

try {
    $replay->play();
} catch(\Gousto\Replay\RetryLogicException $e) {
    
}

next():

The next function allow you to manually control the retry cycle

use Gousto\Replay\Replay;

$replay = Replay::times(3, function() {

    throw new Exception();
  
}, 0, [Exception::class]);

$replay->next(); // 1 attempt
$replay->next(); // 2 attempts
$replay->next(); // Throw RetryLogicException

attempts():

Return the number of retry attempts

use Gousto\Replay\Replay;

$replay = Replay::times(3, function() {

    throw new Exception();
  
}, 0, [Exception::class]);

$replay->next();
$replay->attempts(); // 1

$replay->next();
$replay->attempts(); // 2

isErrored():

Return the state of the function invokation

$replay = Replay::times(4, function() {

    return 10;
  
}, 0, [Exception::class]);

$result = $replay->play(); // 10

$replay->isErrored(); // False

gousto / replay

Maintainers

Details