PHPackages                             ocharai/laravel-idempotency - 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. [Utility & Helpers](/categories/utility)
4. /
5. ocharai/laravel-idempotency

ActiveLibrary[Utility & Helpers](/categories/utility)

ocharai/laravel-idempotency
===========================

Laravel idempotency package with multiple storage support

010PHP

Since Feb 11Pushed 1y ago1 watchersCompare

[ Source](https://github.com/OthmanCharai/Idempotency)[ Packagist](https://packagist.org/packages/ocharai/laravel-idempotency)[ RSS](/packages/ocharai-laravel-idempotency/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Laravel Idempotency
===================

[](#laravel-idempotency)

A robust Laravel package that provides idempotency support for your API endpoints with Redis storage. This package helps prevent duplicate operations when retrying API requests.

Features
--------

[](#features)

- Redis-based storage for idempotency keys
- Configurable TTL for idempotency keys
- Support for multiple HTTP verbs (POST, PUT, PATCH, DELETE)
- User-specific idempotency keys
- Automatic response caching for successful JSON responses
- ULID-based idempotency keys for security and uniqueness

Requirements
------------

[](#requirements)

- PHP ^7.4|^8.0|^8.3
- Laravel ^8.0|^9.0|^10.0|^11.0
- Redis server

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

[](#installation)

You can install the package via composer:

```
composer require ocharai/laravel-idempotency
```

The package will automatically register its service provider.

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

[](#configuration)

Publish the configuration files:

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

This will create two configuration files:

- `config/idempotency.php`: Main package configuration
- `config/database.php`: Redis connection configuration

### Main Configuration Options

[](#main-configuration-options)

```
return [
    // The header key used for idempotency
    'header_key' => env('IDEMPOTENCY_HEADER_KEY', 'X-Idempotency-Key'),

    // Time-to-live for idempotency keys (in seconds)
    'ttl' => env('IDEMPOTENCY_TTL', 86400), // 1 day

    // HTTP verbs that require idempotency
    'enforced_verbs' => [
        'POST',
        'PUT',
        'PATCH',
        'DELETE',
    ],

    // Redis configuration
    'redis' => [
        'connection' => env('IDEMPOTENCY_REDIS_CONNECTION', 'idempotency'),
        'prefix'     => 'idempotency:',
    ],
];
```

### Redis Configuration

[](#redis-configuration)

```
return [
    'redis' => [
        'idempotency' => [
            'client'   => env('REDIS_CLIENT', 'redis'),
            'url'      => env('REDIS_URL'),
            'host'     => env('REDIS_HOST', '127.0.0.1'),
            'username' => env('REDIS_USERNAME'),
            'password' => env('REDIS_PASSWORD'),
            'port'     => env('REDIS_PORT', '6379'),
            'prefix'   => 'idempotency:',
        ],
    ],
];
```

Usage
-----

[](#usage)

1. Add the middleware to your routes or controller:

```
use OCharai\Idempotency\Middleware\IdempotencyMiddleware;

// In a route
Route::post('/api/orders', [OrderController::class, 'store'])
    ->middleware(IdempotencyMiddleware::class);

// Or in a controller
public function __construct()
{
    $this->middleware(IdempotencyMiddleware::class);
}
```

2. Make API requests with an idempotency key:

```
curl -X POST https://your-api.com/api/orders \
    -H "X-Idempotency-Key: 01HNG4V2JXSC0XD6YE4CTWF5QM" \
    -H "Content-Type: application/json" \
    -d '{"product_id": 123}'
```

Note: The idempotency key must be a valid ULID (Universally Unique Lexicographically Sortable Identifier).

### How It Works

[](#how-it-works)

1. When a request is made with an idempotency key, the middleware checks if the key exists in Redis
2. If the key exists and the request method matches, the cached response is returned
3. If the key doesn't exist, the request is processed normally
4. On successful JSON responses, the response is cached with the idempotency key
5. Subsequent requests with the same key within the TTL period will receive the cached response

### Important Notes

[](#important-notes)

- Only successful JSON responses (2xx status codes) are cached
- Idempotency keys are scoped to the authenticated user (if any) and HTTP method
- Keys automatically expire after the configured TTL
- Invalid or missing ULID keys will result in a 400 Bad Request response

Testing
-------

[](#testing)

```
composer test
```

Security
--------

[](#security)

If you discover any security-related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Othman Charai](https://github.com/OthmanCharai)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

15

—

LowBetter than 3% of packages

Maintenance31

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity16

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/928cc153bc9d6eba6c468888491d59178ccc03ef1870d7929c2b3ecc0df14115?d=identicon)[othman charai](/maintainers/othman%20charai)

---

Top Contributors

[![OCharai](https://avatars.githubusercontent.com/u/188989590?v=4)](https://github.com/OCharai "OCharai (17 commits)")

### Embed Badge

![Health badge](/badges/ocharai-laravel-idempotency/health.svg)

```
[![Health](https://phpackages.com/badges/ocharai-laravel-idempotency/health.svg)](https://phpackages.com/packages/ocharai-laravel-idempotency)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)