PHPackages                             infinitypaul/idempotency-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. infinitypaul/idempotency-laravel

ActiveLibrary[HTTP & Networking](/categories/http)

infinitypaul/idempotency-laravel
================================

Elegant and production-ready idempotency middleware for Laravel APIs.

2.0.0(1mo ago)13725.0k↑11.3%8MITPHPPHP ^8.1CI passing

Since Apr 12Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/infinitypaul/idempotency-laravel)[ Packagist](https://packagist.org/packages/infinitypaul/idempotency-laravel)[ RSS](/packages/infinitypaul-idempotency-laravel/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (9)Dependencies (10)Versions (12)Used By (0)

Idempotency for Laravel
=======================

[](#idempotency-for-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/729d61a83b70f748d7d0be1c0cd3cb581e74f5ef0fe7d7c5f4db4a672cde40f2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696e66696e6974797061756c2f6964656d706f74656e63792d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/infinitypaul/idempotency-laravel)

A production-ready Laravel middleware for implementing idempotency in your API requests. Safely retry API calls without worrying about duplicate processing.

What Is Idempotency?
--------------------

[](#what-is-idempotency)

Idempotency ensures that an API operation produces the same result regardless of how many times it is executed. This is critical for payment processing, order submissions, and other operations where duplicate execution could have unintended consequences.

Features
--------

[](#features)

- **Robust Cache Mechanism**: Reliably stores and serves cached responses
- **Lock-Based Concurrency Control**: Prevents race conditions with distributed locks
- **Comprehensive Telemetry**: Track and monitor idempotency operations
- **Alert System**: Get notified about suspicious activity
- **Payload Validation**: Detect when the same key is used with different payloads
- **Detailed Logging**: Easily debug idempotency issues

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require infinitypaul/idempotency-laravel
```

Configuration
-------------

[](#configuration)

```
php artisan vendor:publish --provider="Infinitypaul\Idempotency\IdempotencyServiceProvider"
```

This will create a config/idempotency.php file with the following options:

```
return [
    // Enable or disable idempotency functionality
    'enabled' => env('IDEMPOTENCY_ENABLED', true),

    // HTTP methods that should be considered for idempotency
    'methods' => ['POST', 'PUT', 'PATCH', 'DELETE'],

    // How long to cache idempotent responses (in minutes)
    'ttl' => env('IDEMPOTENCY_TTL', 1440), // 24 hours

    // Cache store to use (null = default store)
    'cache_store' => env('IDEMPOTENCY_CACHE_STORE', null),

    // Validation settings
    'validation' => [
        // Pattern to validate idempotency keys (UUID format by default)
        'pattern' => '/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/',

        // Maximum response size to cache (in bytes)
        'max_length' => env('IDEMPOTENCY_MAX_LENGTH', 10485760), // 10MB
    ],

    // Alert settings
    'alert' => [
        // Number of hits before sending an alert
        'threshold' => env('IDEMPOTENCY_ALERT_THRESHOLD', 5),
    ],

    // Telemetry settings
    'telemetry' => [
        // Default telemetry driver
        'driver' => env('IDEMPOTENCY_TELEMETRY_DRIVER', 'inspector'),

        // Custom driver class if using 'custom' driver
        'custom_driver_class' => null,
    ],
];
```

Using a Dedicated Cache Store
-----------------------------

[](#using-a-dedicated-cache-store)

By default the middleware uses your application's default cache store. This means running `php artisan cache:clear` will also wipe cached idempotency responses. To avoid this, point the package at its own store:

1. Define a new store in `config/cache.php`:

```
'stores' => [
    // ... your other stores ...

    'idempotency' => [
        'driver' => 'redis',
        'connection' => 'default',
        'prefix' => 'idempotency',
    ],
],
```

2. Set the store in `config/idempotency.php` (or via `.env`):

```
'cache_store' => env('IDEMPOTENCY_CACHE_STORE', 'idempotency'),
```

```
IDEMPOTENCY_CACHE_STORE=idempotency
```

Now `php artisan cache:clear` only clears the default store, leaving idempotency data intact.

To clear the idempotency cache when needed, target the store explicitly:

```
php artisan cache:clear --store=idempotency
```

Usage
-----

[](#usage)

Add the middleware to your routes or route groups in your routes/api.php file:

```
Route::middleware(['auth:api', \Infinitypaul\Idempotency\Middleware\EnsureIdempotency::class])
    ->group(function () {
        Route::post('/payments', [PaymentController::class, 'store']);
        // Other routes...
    });
```

### Using With Requests

[](#using-with-requests)

To make an idempotent request, clients should include an Idempotency-Key header with a unique UUID:

```
POST /api/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

{
  "amount": 1000,
  "currency": "USD",
  "description": "Order #1234"
}
```

If the same idempotency key is used again with the same payload, the original response will be returned without re-executing the operation.

Response Headers
----------------

[](#response-headers)

The middleware adds these headers to responses:

- `Idempotency-Key`: The key used for the request
- `Idempotency-Status`: Either `Original` (first request) or `Repeated` (cached response)

Telemetry
---------

[](#telemetry)

The package provides built-in telemetry through various service. The telemetry records:

- Request processing time
- Cache hits and misses
- Lock acquisition time
- Response sizes
- Error rates

Telemetry Drivers
-----------------

[](#telemetry-drivers)

I intend to add more drivers in my free time

- Inspector ()

Custom Driver
-------------

[](#custom-driver)

To use a custom telemetry driver, implement the TelemetryDriver interface:

```