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.

1.0.5(11mo ago)13317.5k—2.5%7[1 issues](https://github.com/infinitypaul/idempotency-laravel/issues)[1 PRs](https://github.com/infinitypaul/idempotency-laravel/pulls)MITPHPPHP ^8.1

Since Apr 12Pushed 3mo 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 1mo ago

READMEChangelog (6)Dependencies (4)Versions (7)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

    // 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,
    ],
];
```

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:

```