PHPackages ademakanaky/laravel-enterprise-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. [HTTP & Networking](/categories/http) 4. / 5. ademakanaky/laravel-enterprise-idempotency ActiveLibrary[HTTP & Networking](/categories/http) ademakanaky/laravel-enterprise-idempotency ========================================== Enterprise-grade, concurrency-safe idempotency middleware for Laravel APIs. 1.0.0(3mo ago)10MITPHPPHP ^8.3 Since Mar 6Pushed 3mo agoCompare [ Source](https://github.com/ademakanaky/laravel-idempotency)[ Packagist](https://packagist.org/packages/ademakanaky/laravel-enterprise-idempotency)[ RSS](/packages/ademakanaky-laravel-enterprise-idempotency/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (6)Versions (2)Used By (0) Laravel Enterprise Idempotency ============================== [](#laravel-enterprise-idempotency) [![Laravel](https://camo.githubusercontent.com/93554d1ac44e7880097a6bd117e99f90c33ddf03dcf0a37f3047fa50b8aaa4d2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302532422d726564)](https://camo.githubusercontent.com/93554d1ac44e7880097a6bd117e99f90c33ddf03dcf0a37f3047fa50b8aaa4d2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302532422d726564)[![PHP](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)[![Tests](https://camo.githubusercontent.com/d940ad7f0752e2cbe0d63c50dcebf329078807390051c41fe63258f1b5c4e182/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d70617373696e672d627269676874677265656e)](https://camo.githubusercontent.com/d940ad7f0752e2cbe0d63c50dcebf329078807390051c41fe63258f1b5c4e182/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d70617373696e672d627269676874677265656e) **Enterprise-grade Idempotency Middleware for Laravel APIs** This package prevents **duplicate request processing** and safely **replays the original response** when a client retries a request using the same `Idempotency-Key`. It is designed for **financial systems, payment APIs, fintech platforms, loan services, and mission‑critical backend systems** where duplicate processing must be prevented. --- Table of Contents ================= [](#table-of-contents) - Features - Installation - Basic Usage - How Idempotency Works - Drivers - Configuration - Request Hash Protection - Automatic User Scoping - Response Replay - Example Payment Flow - Testing - Package Structure - Security Considerations - Example Idempotency Key Generation - Contributing - License --- Features ======== [](#features) - Multiple idempotency drivers - Cache driver - Database driver - Hybrid driver (Database + Cache Lock) - Automatic response replay - Request hash validation - Per-user idempotency scope - Configurable response status codes - Distributed locking support - Replay count tracking - Pluggable driver architecture - Fully tested (Unit + Feature tests) --- Installation ============ [](#installation) Install the package via Composer: ``` composer require ademakanaky/laravel-idempotency ``` Publish the configuration: ``` php artisan vendor:publish --tag=idempotency-config ``` Publish the migration: ``` php artisan vendor:publish --tag=idempotency-migrations ``` Run migrations: ``` php artisan migrate ``` --- Basic Usage =========== [](#basic-usage) Apply the middleware to routes that require idempotency protection. ``` Route::post('/payments', PaymentController::class) ->middleware('idempotency'); ``` Clients must include an **Idempotency-Key** header. Example request: ``` POST /payments Idempotency-Key: PAY-123456789 ``` --- How Idempotency Works ===================== [](#how-idempotency-works) First Request ------------- [](#first-request) Client sends request: ``` Idempotency-Key: abc123 ``` 1. The request is processed normally. 2. The response is stored. 3. The idempotency key is recorded. --- Retry Request ------------- [](#retry-request) Client retries using the same key: ``` Idempotency-Key: abc123 ``` Instead of executing the request again: - The stored response is returned. - The request handler is not executed again. Response header: ``` Idempotency-Replayed: true ``` --- Drivers ======= [](#drivers) Driver configuration is located at: ``` config/idempotency.php ``` Cache Driver ------------ [](#cache-driver) Uses Laravel cache to store responses. Best for: - Short‑lived APIs - Lightweight operations ``` ``` ``` driver = cache ``` --- Database Driver --------------- [](#database-driver) Stores request and response data in the database. Best for: - Financial systems - Audit trails - Compliance environments ``` ``` ``` driver = database ``` --- Hybrid Driver (Recommended) --------------------------- [](#hybrid-driver-recommended) Uses: - Cache locking - Database persistence Benefits: - Prevents concurrent duplicate processing - Ensures durable response replay ``` ``` ``` driver = hybrid ``` --- Configuration ============= [](#configuration) Example configuration file: ``` return [ 'driver' => env('IDEMPOTENCY_DRIVER', 'hybrid'), 'ttl_minutes' => 60, 'status_codes' => [ 200, 201, 202, ], 'lock' => [ 'enabled' => true, 'seconds' => 10, ], 'idempotency_model' => \Ademakanaky\EnterpriseIdempotency\Models\IdempotencyRecord::class, ]; ``` --- Request Hash Protection ======================= [](#request-hash-protection) Requests are hashed using: ``` HTTP Method + Route + Request Body ``` If the same `Idempotency-Key` is reused with **different request data**, the request will fail. Example response: ``` 409 Conflict Idempotency key conflict ``` This ensures request integrity. --- Automatic User Scoping ====================== [](#automatic-user-scoping) Idempotency keys are automatically scoped to avoid collisions. Priority: 1. Authenticated User ID 2. Client IP Address This prevents two different users from accidentally sharing the same idempotency key. --- Response Replay =============== [](#response-replay) When a stored response is returned, the API includes the header: ``` Idempotency-Replayed: true ``` This allows API clients to detect that a response came from a retry. --- Example Payment Flow ==================== [](#example-payment-flow) ### Initial Request [](#initial-request) ``` POST /payments Idempotency-Key: PAY-001 ``` A network failure occurs before the client receives the response. ### Client Retry [](#client-retry) ``` POST /payments Idempotency-Key: PAY-001 ``` Instead of creating a second payment, the API returns the **original stored response**. --- Architecture Overview ===================== [](#architecture-overview) ``` Client | | POST /payments | Idempotency-Key v Idempotency Middleware | |-- Check existing key |-- Validate request hash |-- Acquire lock (Hybrid) | v Application Controller | v Response Stored | v Future retries replay stored response ``` --- Testing ======= [](#testing) Run the full test suite: ``` vendor/bin/phpunit ``` Test coverage includes: - Unit Tests - Feature Tests - Driver Tests - Middleware Concurrency Tests --- Package Structure ================= [](#package-structure) ``` laravel-idempotency │ ├── src │ ├── Contracts │ │ └── IdempotencyDriver.php │ │ │ ├── Drivers │ │ ├── CacheDriver.php │ │ ├── DatabaseDriver.php │ │ └── HybridDriver.php │ │ │ ├── Http │ │ └── Middleware │ │ └── IdempotencyMiddleware.php │ │ │ ├── Models │ │ └── IdempotencyRecord.php │ │ │ ├── Providers │ │ └── IdempotencyServiceProvider.php │ │ │ └── Services │ └── IdempotencyManager.php │ ├── config │ └── idempotency.php │ ├── database │ └── migrations │ ├── tests │ ├── Feature │ └── Unit │ ├── composer.json └── phpunit.xml ``` --- Security Considerations ======================= [](#security-considerations) This package ensures: - Duplicate requests are **not processed twice** - Safe retry behavior - Request integrity validation - Replay protection Recommended for: - Payment APIs - Loan systems - Order processing - Financial microservices - Distributed systems --- Example Idempotency Key Generation ================================== [](#example-idempotency-key-generation) Clients should generate unique idempotency keys. Example in Laravel: ``` use Illuminate\Support\Str; $key = 'PAY-' . Str::uuid(); ``` Example request header: ``` Idempotency-Key: PAY-550e8400-e29b-41d4-a716-446655440000 ``` --- Contributing ============ [](#contributing) Pull requests are welcome. Please ensure all tests pass before submitting: ``` vendor/bin/phpunit ``` --- TO-DO: ====== [](#to-do) - Add Idempotency Expiration Cleanup Command – this is important so the idempotency\_keys table does not grow indefinitely. - Still thinking about what else to add... License ======= [](#license) MIT License ### Health Score 36 — LowBetter than 79% of packages Maintenance79 Regular maintenance activity Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity49 Maturing project, gaining track record 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. ### Release Activity Cadence Unknown Total 1 Last Release 112d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/22824390?v=4)[Oluwasegun Ibidokun](/maintainers/ademakanaky)[@ademakanaky](https://github.com/ademakanaky) --- Top Contributors [![ademakanaky](https://avatars.githubusercontent.com/u/22824390?v=4)](https://github.com/ademakanaky "ademakanaky (2 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/ademakanaky-laravel-enterprise-idempotency/health.svg) ``` [![Health](https://phpackages.com/badges/ademakanaky-laravel-enterprise-idempotency/health.svg)](https://phpackages.com/packages/ademakanaky-laravel-enterprise-idempotency) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.1M337](/packages/psalm-plugin-laravel)[mike-bronner/laravel-model-caching Automatic caching for Eloquent models. 2.4k55.1k1](/packages/mike-bronner-laravel-model-caching)[api-platform/laravel API Platform support for Laravel 59156.3k11](/packages/api-platform-laravel)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum)[pressbooks/pressbooks Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS. 45344.0k1](/packages/pressbooks-pressbooks) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)