Introduction

The Problem

Distributed systems are unreliable by nature. Networks drop, clients retry, jobs fail and get picked up again. Without protection, the same operation can execute multiple times — with real consequences.

Consider two common scenarios:

Order processing — A client submits an order and loses the connection before receiving a response. It retries. The server processes the order twice, creating a duplicate.

Email notification — A queued job sends a confirmation email, then fails before marking itself complete. On retry, the email goes out again.

These are not edge cases. They are expected failure modes in any production system.

How truschery/idem Solves This

truschery/idem assigns a unique key to each operation. On the first call — the operation executes and the result is stored. On any subsequent call with the same key — the stored result is returned immediately, without re-executing.

One key. One execution. No matter how many times it's called.

What truschery/idem Covers

HTTP Requests — Middleware that intercepts incoming requests and replays cached responses based on the Idempotency-Key header. → HTTP Middleware

Queued Jobs — Job middleware that prevents a job from executing more than once, even across retries. → Job Middleware

Arbitrary Code — A simple facade to wrap any operation with an idempotency guarantee. → Facade

Quick Start

use Truschery\Idem\Facades\Once;

Once::do('send-welcome-email-user-42', function () {
    Mail::to($user)->send(new WelcomeMail());
});

Pass a unique key and a callback. If this key has been seen before — the callback won't run.