wendelladriel/laravel-idempotency

HTTP Idempotency Middleware for Laravel applications

v1.1.0 2026-04-23 15:02 UTC

Requires

• php: ^8.3
• illuminate/support: ^13.0

Requires (Dev)

• laravel/pint: ^1.29
• nunomaduro/pao: ^1.0
• orchestra/testbench: ^11.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-type-coverage: ^4.0
• phpstan/phpstan: ^2.1
• rector/rector: ^2.4

MIT

• Wendell Adriel

• http
• api
• laravel
• idempotency

README

Laravel Idempotency

HTTP idempotency middleware for Laravel applications

Installation

You can install the package via composer:

composer require wendelladriel/laravel-idempotency

You can publish the config file with:

php artisan vendor:publish --tag="idempotency"

Usage

Attach the middleware to routes that create or update data:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use WendellAdriel\Idempotency\Http\Middleware\Idempotent;

Route::post('/orders', function (Request $request) {
    return response()->json([
        'id' => 1,
        'item' => $request->input('item'),
    ], 201);
})->middleware(Idempotent::class);

By default, the middleware expects an Idempotency-Key header. When the same key is sent again with the same request data, the package replays the original response instead of executing your route again.

Customize a single route with Idempotent::using:

use WendellAdriel\Idempotency\Enums\IdempotencyScope;
use WendellAdriel\Idempotency\Http\Middleware\Idempotent;

Route::post('/payments', ChargePaymentController::class)->middleware(
    Idempotent::using(
        ttl: 600,
        required: false,
        scope: IdempotencyScope::Ip,
        header: 'X-Idempotency-Key',
        lockTimeout: 30,
    )
);

You may also use the idempotent middleware alias:

Route::post('/orders', StoreOrderController::class)->middleware('idempotent');

If you prefer attributes, use the package's #[Idempotent] attribute on a controller class or method:

use Symfony\Component\HttpFoundation\Response;
use WendellAdriel\Idempotency\Attributes\Idempotent;

#[Idempotent]
class OrderController
{
    public function store(): Response
    {
        // ...
    }
}

Generate a key in application code when needed:

use WendellAdriel\Idempotency\Idempotency;

$key = Idempotency::key();

Inspect and prune cached entries with the included Artisan commands:

php artisan idempotency:list
php artisan idempotency:forget --key=checkout-1 --force

Access the full documentation here.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Laravel Idempotency! You can read the contribution guide here.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Wendell Adriel
• All Contributors

License

Laravel Idempotency is open-sourced software licensed under the MIT license.