algoyounes/idempotency

Laravel Idempotency Middleware package to prevent duplicate requests

v1.1.0 2025-04-17 13:59 UTC

This package is not auto-updated.

Last update: 2025-06-05 18:44:51 UTC


README

Laravel Idempotency Logo
Idempotency

Build Status Total Downloads Latest Stable Version License

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.