Skip to content
YII3-IDEMPOTENCY(3)rasuvaeff PHP Library ManualYII3-IDEMPOTENCY(3)

NAME ​

yii3-idempotency — idempotency-key PSR-15 middleware that stops duplicate POST, PUT and PATCH processing

SYNOPSIS ​

$ composer require rasuvaeff/yii3-idempotency

$middleware = new IdempotencyMiddleware(    keyExtractor: new HeaderIdempotencyKeyExtractor(),    storage: new InMemoryIdempotencyStorage($clock),    responseFactory: $responseFactory,    clock: $clock,    scopeResolver: new RequestAttributeScopeResolver(attribute: 'user'),who a key belongs to    ttlSeconds: 3600,);

DESCRIPTION ​

PSR-15 middleware for Idempotency-Key. The same key and body run the handler once.

Retried or double-submitted requests run the handler twice. Without caller scoping, one client could also replay or lock out another client's key.

  • Same key and same payload replays the stored response with Idempotency-Replay: true.
  • Same key and a different payload answers 422; an in-flight duplicate answers 409.
  • The fingerprint covers method, path, query and body.
  • scopeResolver is required: keys are namespaced per caller.
  • 2xx responses are cached by default; other statuses release the claim.
  • DomainFailureRenderer and FailureClassifier cache domain failures, so InsufficientFunds is not executed again.
  • cacheableRedirectStatuses caches 303 for Post/Redirect/Get forms.
  • Set-Cookie, Date and hop-by-hop headers are never captured.

EXAMPLES ​

Caches deterministic domain failures as replayable responses while bugs and infra errors stay retryable.

$middleware = new IdempotencyMiddleware(    keyExtractor: new HeaderIdempotencyKeyExtractor(),    storage: $storage,    responseFactory: $responseFactory,    clock: $clock,    scopeResolver: new RequestAttributeScopeResolver(attribute: 'user'),    domainFailureRenderer: $renderer,your DomainFailureRenderer    failureClassifier: new DefaultFailureClassifier([optional overrides        MisconfiguredGatewayException::class => FailureKind::Bug,    ]),);

Stores and replays a 303 redirect so a double-submitted form never runs the handler twice.

$middleware = new IdempotencyMiddleware(    // ... keyExtractor, storage, responseFactory, clock, scopeResolver ...    cacheableRedirectStatuses: [303],);

Scopes idempotency keys by caller and endpoint so identical keys never collide.

// caller + "METHOD /path" — the wiring the bundled config builds by default$scopeResolver = new CompositeScopeResolver(    new RequestAttributeScopeResolver(attribute: 'user'),    new RequestTargetScopeResolver(),); // caller + an explicit namespace shared by related endpoints$scopeResolver = new CompositeScopeResolver(    new RequestAttributeScopeResolver(attribute: 'user'),    new IdempotencyScope('orders'),);

SEE ALSO ​

yii3-idempotency-db provides DbIdempotencyStorage; yii3-idempotency-redis is the Redis backend.

BUGS ​

Anonymous callers share one namespace, so do not put caller-private data behind an anonymous idempotent endpoint. SharedKeyspaceScopeResolver is a documented opt-out, safe only for a single principal.

DEPENDENCIES

required by: yii3-idempotency-db(3), yii3-idempotency-redis(3)

HISTORY

First released as v1.0.0 on 2026-06-12; 9 releases in all.

v2.3.02026-10-27
v2.2.02026-10-26
v2.1.02026-08-29
v2.0.12026-08-25
v2.0.02026-08-22
v1.1.12026-07-25
v1.1.02026-07-24
v1.0.12026-06-27
v1.0.02026-06-12
rasuvaeff/yii3-idempotency 2.3.0mutation gate 98%used by 2 packagesYII3-IDEMPOTENCY(3)

/ search · n N next, previous · g G top, bottom · q back to the index