- How do I install and enable laravel-idempotency in a Laravel app?
- Install it with composer require wendelladriel/laravel-idempotency, then register the middleware on the route groups that need idempotent behavior. You may publish the config file if you need to change storage, locking, or header settings. No controller signature changes are required because it works at Laravel's HTTP middleware layer.
- Which Laravel and PHP versions does laravel-idempotency support?
- The package targets Laravel's HTTP middleware layer, but its composer.json and CI configuration are the authoritative source for supported Laravel and PHP versions. The v1.5.1 release notes do not add a visible LTS commitment, so verify the tested matrix before adopting. Run a smoke test on the exact Laravel and PHP versions you deploy.
- How does the middleware prevent duplicate requests?
- It reads the idempotency key from the configured request header, builds a fingerprint of the request, and stores a record keyed by that key. When a duplicate arrives, the middleware can replay the stored response or block the request instead of running the controller again. Correctness depends on the store and lock being atomic.
- Which header should clients send for the idempotency key?
- The package uses an idempotency header, but you should confirm the exact header name and whether it is configurable in the package config. Many teams standardize on Idempotency-Key and have the client generate a UUID per logical operation. Agree the header contract with API consumers before rollout.
- What happens if the same idempotency key is reused with a different payload?
- The package uses a request fingerprint to detect reuse of the same idempotency key with a different payload. v1.5.1 narrowed fingerprinting so fallback/default inputs are excluded, reducing spurious key-conflict errors. The exact conflict status code and body should be confirmed in the docs/config, and clients should distinguish it from validation errors.
- Which storage backends can laravel-idempotency use?
- Storage is configurable, and the package is commonly discussed with cache-backed stores; some setups may also use Redis or a database-backed store. What matters most is atomicity: avoid non-atomic cache has/put sequences and ensure any distributed lock works across all app instances. Check the documented guarantees for each store before production.
- Is laravel-idempotency safe for payments and orders in production?
- It can help protect payments and orders by making retries safe when clients resend the same key. It is not a replacement for domain-level idempotency in your payment or order workflow. Use an atomic store and lock, set a sensible TTL, and test conflict behavior under concurrent requests.
- Does it work with Laravel Octane and multiple app instances?
- It should work under Laravel Octane and across multiple instances only if the store and locking are shared and atomic across nodes. A per-process cache or non-distributed lock can silently degrade the guarantee to usually idempotent. Include a concurrent multi-worker test in your spike before relying on it.
- How long are idempotency keys and stored responses retained?
- Stored responses and keys should be pruned by a TTL, but the default retention and size limits should be verified in the package config. Response replay can persist tokens, PII, or signed URLs, so treat the store as sensitive data and consider encryption and retention policy. Check whether bodies are encrypted and capped in your chosen store.
- What changed in v1.5.1 and is the package actively maintained?
- v1.5.1 is a patch release that excludes fallback input from request fingerprints to avoid spurious key-conflict errors, plus a CI-only deploy-pages bump. It has no breaking changes, but in-flight keys created before upgrade with fallback-input requests may fingerprint differently. The package is small and maintainer-driven, so confirm maintenance expectations and test upgrades.