Laravel Idempotency

Framework-native HTTP idempotency for Laravel applications.

[](https://github.com/AdilAzhari/laravel-idempotency/actions/workflows/tests.yml)   

Why Another Idempotency Package?

Laravel applications commonly implement idempotency in an ad-hoc manner, often coupling request replay, persistence, and locking into application code.

Laravel Idempotency provides a reusable, framework-native solution built around explicit contracts and interchangeable components, allowing storage, fingerprinting, and locking strategies to evolve independently.

Laravel Idempotency

Laravel Idempotency provides a framework-native solution for ensuring that identical HTTP requests are executed exactly once.

Using an Idempotency-Key, the package stores the original HTTP response and automatically replays it for subsequent identical requests, eliminating accidental duplicate operations caused by retries or network failures.

It is particularly useful for:

• Payment processing
• Subscription management
• Order creation
• Inventory updates
• Account changes
• External API integrations
• Webhook processing

Why Idempotency?

Distributed systems are unreliable.

Clients retry requests.

Browsers retry requests.

Mobile applications automatically retry after network interruptions.

Load balancers and reverse proxies may resend requests.

Without idempotency, a single retry can unintentionally create duplicate:

• Payments
• Orders
• Invoices
• Subscriptions
• Shipments
• Customer accounts

Laravel Idempotency guarantees that the same logical operation executes only once while returning the original response for every identical retry.

Features

• HTTP idempotency middleware
• Job idempotency middleware, protecting queued job side effects from retries and redelivery
• HTTP-to-job idempotency key propagation via IdempotencyContext
• Atomic request locking
• Automatic response replay
• SHA-256 request fingerprinting
• Configurable response expiration
• Configurable HTTP method scope (skips safe methods like GET by default)
• Idempotency-Replayed response header on every protected response
• Idempotency key length validation
• Multiple storage drivers
  • Array
  • Cache
  • Redis
  • Database
• Database pruning command
• Custom fingerprint strategies
• Custom storage implementations
• Laravel-native dependency injection
• Fully tested
• Production-ready

Requirements

• PHP 8.5+
• Laravel 13+

For production deployments, use a shared storage backend such as Redis or the Database driver.

Installation

Install the package using Composer.

Laravel automatically discovers the package.

Publish the configuration file:

If you intend to use the database storage driver, also publish the migration:

Quick Start

Protect any write endpoint using the middleware.

Clients simply provide an idempotency key.

The first request executes normally.

Subsequent identical requests return the previously stored response without executing the controller again.

How It Works

Request Matching

Two requests are considered identical when all of the following match:

• Idempotency key
• HTTP method
• Request path
• Query parameters
• Parsed request body

The default implementation uses the built-in Sha256RequestFingerprinter.

For example:

and

are treated as different requests, even if they share the same idempotency key.

If the same key is reused for different request data, an IdempotencyConflictException is thrown and rendered as a 409 Conflict JSON response.

Error Responses

All three exceptions are self-rendering, so no custom exception handler registration is required.

JobIdempotencyMiddleware throws the equivalent plain exceptions for jobs — JobIdempotencyConflictException and JobIdempotencyLockConflictException — which are not self-rendering, since a queue worker has no HTTP response to render.

Jobs

Idempotency isn't only an HTTP concern. Laravel's own ShouldBeUnique/WithoutOverlapping prevent concurrent duplicate dispatch, but they don't protect against a job's side effects running twice after a retry-following-partial-success, an at-least-once queue redelivery, or two separate dispatches of the same logical action (e.g. a webhook retried by its sender).

JobIdempotencyMiddleware protects a job's side effects the same way IdempotencyMiddleware protects HTTP responses: a stable key, atomic locking, and a persisted record so a duplicate execution is skipped rather than re-run.

If the same key is later reused for a job with a different payload, a JobIdempotencyConflictException is thrown — the job-side equivalent of IdempotencyConflictException.

Connecting an HTTP Request to the Job It Dispatches

IdempotencyContext lets a job adopt the idempotency key of the HTTP request that triggered it, so one key protects both layers.

IdempotencyContext::current() returns the key from the current HTTP request when one was processed by IdempotencyMiddleware, or null outside of a request — falling back to your own key is always recommended.

Storage Drivers

Laravel Idempotency supports multiple persistence backends.

Select the active driver through configuration.

Switching drivers requires no application code changes.

Configuration

The lock duration should comfortably exceed the execution time of your protected endpoints.

Extending

Laravel Idempotency is built around a small set of contracts, allowing individual components to be replaced without modifying the package.

Custom Request Fingerprinting

Bind your own implementation of the RequestFingerprinter contract.

Possible use cases include:

• Ignoring selected request fields
• Including additional HTTP headers
• Supporting custom hashing algorithms
• Multi-tenant request isolation

Custom Storage

Implement the IdempotencyStore contract to persist responses anywhere.

Possible implementations include:

• Redis
• Database
• DynamoDB
• MongoDB
• Amazon S3
• External persistence services

Custom Locking

Locking is also replaceable.

This allows integration with:

• Redis locks
• Database locks
• Distributed lock services
• Cloud-native coordination systems

Storage Drivers

Cache Driver

The Cache driver is the default storage implementation.

It stores responses using Laravel's configured cache store and is suitable for most applications.

Array Driver

The Array driver stores responses in memory.

This driver is intended for:

• Unit tests
• Local development
• Temporary storage

Because data exists only in memory, it should not be used in production.

Redis Driver

The Redis driver stores responses directly in Redis.

Configuration:

This driver is recommended for distributed deployments where multiple application instances must share idempotency records.

Database Driver

The Database driver persists responses using Eloquent.

Before using it, publish the migration:

The database driver provides durable storage that survives cache flushes and application restarts.

Pruning Expired Records

Expired database records can be removed using the built-in Artisan command.

Scheduling the command is recommended.

Design Principles

Laravel Idempotency is intentionally built around a small set of principles.

• Framework-native integration
• Explicit contracts
• Predictable behaviour
• Simple public API
• Testability
• Extensibility

Testing

Run the complete test suite.

The package includes comprehensive unit and feature tests covering:

• Request replay
• Conflict detection
• Request fingerprinting
• Atomic locking
• Cache storage
• Redis storage
• Database storage
• Array storage
• Middleware integration
• Service provider registration
• Configuration
• Console commands

Documentation

Additional documentation is available in the docs directory.

• Architecture
• Storage Drivers
• Custom Fingerprinting
• Custom Storage Drivers
• Custom Locking
• Contributing Guide

Roadmap

• ✅ Laravel 13 support
• ✅ HTTP idempotency middleware
• ✅ Atomic request locking
• ✅ SHA-256 request fingerprinting
• ✅ Cache storage driver
• ✅ Array storage driver
• ✅ Redis storage driver
• ✅ Database storage driver
• ✅ Configurable storage drivers
• ✅ Database pruning command
• ✅ Job idempotency middleware
• ✅ HTTP-to-job idempotency key propagation
• 🚧 Additional storage adapters
• 🚧 Step-level checkpointing within a job (resumable partial execution)

Contributing

Contributions are welcome.

If you discover a bug or would like to propose a new feature, please open an issue before submitting a pull request so the implementation can be discussed first.

When contributing:

• Follow the existing coding style.
• Include tests for new functionality.
• Ensure composer test passes before opening a pull request.

License

Laravel Idempotency is open-source software licensed under the MIT License.