algoyounes / idempotency
Laravel Idempotency Middleware package to prevent duplicate requests
Requires
- php: ^8.2
Requires (Dev)
- laravel/framework: ^11.0
- laravel/pint: ^1.13.7
- orchestra/testbench: ^9.0
- pestphp/pest: ^2.28.1
- phpstan/phpstan: ^2.1
- rector/rector: ^2.0
Suggests
- illuminate/contracts: for the Laravel integration
- illuminate/foundation: for the Laravel integration
- illuminate/http: for the Laravel integration
- illuminate/support: for the Laravel integration
This package is not auto-updated.
Last update: 2025-06-05 18:44:51 UTC
README
Idempotency is a Laravel package that helps you make your requests idempotent. Idempotent requests can be safely retried without causing any side effects. This is useful when you're dealing with unreliable networks or when you want to prevent duplicate requests from being processed.
Features ✨
- Idempotent Requests: Ensure that requests can be safely retried without side effects.
- Middleware Integration: Easily add
idempotency
middleware to routes or route groups. - Customizable Cache: Configure cache TTL and store for idempotency keys.
- Duplicate Handling: Choose between replaying cached responses or throwing exceptions for duplicate requests.
- Custom Resolvers: Implement custom logic for resolving user IDs or generating cache keys.
- Header-Based Idempotency: Use the
Idempotency-Key
header to identify requests. - Race Condition Handling: Prevent race conditions with configurable lock wait times.
- Unauthenticated Support: Define a default user ID name for unauthenticated requests.
Installation
You can install the package via Composer:
composer require algoyounes/idempotency
You can publish the configuration file using the following command:
php artisan vendor:publish --provider="AlgoYounes\Idempotency\Providers\IdempotencyServiceProvider" --tag="config"
Here are the available options in the configuration file:
Option | Default Value | Description |
---|---|---|
enable |
true |
Enable or disable the idempotency middleware |
cache.ttl |
86400 (1 Day) |
The time-to-live for idempotency keys in minutes |
cache.store |
default |
The cache store to use for idempotency keys |
idempotency_header |
Idempotency-Key |
The header to use for idempotency keys |
idempotency_relayed_header |
Idempotency-Relayed |
The header for relaying idempotency keys |
duplicate_handling |
replay |
The action to take when a duplicate request is detected. Options are replay or exception |
enforced_verbs |
['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] |
The HTTP verbs to enforce idempotency on |
max_lock_wait_time |
10 (10 seconds) |
The maximum time to wait for a lock in seconds |
user_id_resolver |
null |
The user ID resolver to use for generating cache keys |
unauthenticated_user_id |
guest |
The default user ID name for unauthenticated requests |
Usage
To request idempotent, try adding something like idempotency
middleware to the route or group of routes you want to protect. The middleware will check if the request is idempotent by looking for the Idempotency-Key
header. If the header is present, the middleware will cache the response and reuse it for subsequent requests with the same key.
Route::middleware('idempotency')->post('/orders', 'OrderController@store');
You can also add the middleware to a group of routes:
Route::middleware('idempotency')->group(function () { Route::post('/orders', 'OrderController@store'); Route::get('/orders/{id}', 'OrderController@show'); });
Custom Resolver 🔧
You can create your resolver by implementing the Resolver
interface.
This is useful when you want to store the cache in a different store or when you want to customize the key generation logic.
use AlgoYounes\Idempotency\Contracts\Resolver; class CustomUserIdResolver implements Resolver { public function resolve(): string { // Your custom logic here } } // In the configuration file 'user_id_resolver' => CustomUserIdResolver::class,
Contributing
Thank you for considering contributing to the Idempotency package. For more details, please check the CONTRIBUTING file.
License
The Idempotency package is open-sourced software licensed under the MIT license.