filipefernandes/laravel-route-retry

A Laravel package to capture and retry failing requests.

0.0.1 2026-01-09 10:13 UTC

Requires

• php: ^8.1
• illuminate/console: ^10.0|^11.0|^12.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/filesystem: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Filipe Fernandes

README

Laravel Route Retry adds a simple and flexible way to capture failed requests (5xx) and retry them later. It's perfect for handling transient failures in webhooks, external API calls, or any critical route.

Installation

You can install the package via composer:

composer require filipefernandes/laravel-route-retry

You can publish the config file with:

php artisan vendor:publish --tag="retry-config"

Then, run the migrations:

php artisan migrate

Usage

Simple Route Retry

You can enable retries on any route using the retry() macro:

use Illuminate\Support\Facades\Route;

Route::post('/webhooks/stripe', function () {
    // If this fails with 5xx, it will be captured
})->retry(3); // Retry up to 3 times

Adding Tags

Tags help you filter and process retries for specific features:

Route::post('/sync-data', [SyncController::class, 'handle'])
    ->retry(5)
    ->tags(['erp', 'priority-high']);

Processing Retries

To process pending retries, add the following command to your app/Console/Kernel.php:

$schedule->command('retry:process')->everyMinute();

You can also filter retries by tag or ID:

php artisan retry:process --tag=erp
php artisan retry:process --id=1 --id=2 --id=3
php artisan retry:process --fingerprint=a8...

Configuration

The published configuration file config/retry.php allows you to customize:

• table_name: The table where retries are stored.
• storage_disk: The disk used for temporary file storage (defaults to local).
• max_retries: Global default for maximum retry attempts.
• delay: The initial delay before the first retry attempt.

Events

The package dispatches events throughout the retry lifecycle:

• LaravelRouteRetry\Events\RequestCaptured: Dispatched when a failure is first captured.
• LaravelRouteRetry\Events\RetrySucceeded: Dispatched when a retry attempt results in a 2xx response.
• LaravelRouteRetry\Events\RetryFailed: Dispatched when a retry fails or reaches the maximum limit.

License

The MIT License (MIT). Please see License File for more information.