README

Stripe-style Idempotency-Key middleware for multi-tenant Laravel APIs.

• Requires an idempotency header on mutating requests
• Cache-locks concurrent retries
• Replays the stored response on matching payload
• Returns 409 Conflict when the same key is reused with a different body
• Prunes expired records via Eloquent's Prunable

Requirements

• PHP 8.2+
• Laravel 12 or 13

Installation

composer require boone-studios/laravel-idempotency

php artisan vendor:publish --tag=idempotency-config
php artisan vendor:publish --tag=idempotency-migrations
php artisan migrate

Configuration

scope_resolver must be configured before you use this middleware. There is no default implementation — the package ships as null and will throw a RuntimeException at request time (with a message pointing back to this config key) if you register the idempotency middleware on a route without setting it first.

Implement BooneStudios\Idempotency\Contracts\ResolvesIdempotencyScope and set it in config/idempotency.php:

'scope_resolver' => App\Services\TenantContext::class,
'scope_column' => 'tenant_id', // or vendor_id, organization_id, …

Register the middleware:

Route::middleware('idempotency')->post('/orders', …);

Only apply the idempotency middleware to routes where a scope/tenant is always resolvable (e.g. authenticated, tenant-scoped endpoints). Routes that legitimately have no tenant yet (e.g. a signup endpoint) should not use this middleware — resolution failure is treated as a configuration error, not a "no tenant" case.

License

MIT © Boone Studios, LLC