README

Laravel Idempotency

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 reads the key from the Idempotency-Key header or the _idempotency_key request input. This allows standard HTML forms to include the key in a hidden input. When both values are present, the header takes precedence.

Use the @idempotency Blade directive to render the hidden input with a generated key:

<form method="POST" action="/orders">
    @csrf
    @idempotency

    <!-- ... -->
</form>

You may pass an existing key with @idempotency($key).

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.