A database commit is a promise: the order exists, the payment state changed, the account was created. An event sent to another system is also a promise. The trouble starts when an application tries to make both promises independently.

Imagine a PHP endpoint that saves an order and then publishes OrderPlaced to a message broker. If the database transaction succeeds but the process crashes before publishing, downstream systems never learn about the order. If the message is published first and the transaction later rolls back, consumers receive an event for something that does not exist.

The transactional outbox pattern solves this awkward gap without pretending a database and a broker share one atomic transaction. It makes the database the reliable handoff point, then delivers events from a durable outbox after the business change has committed.

The core idea: commit data and intent together

An outbox is a database table containing messages that still need to be delivered. During the same transaction that updates application data, the application inserts an outbox row describing the event. One commit makes both the state change and the intent to notify durable.

A separate worker reads pending rows and sends them to the broker, webhook endpoint, or another integration. Once delivery succeeds, the worker marks the row as processed.

This deliberately changes the guarantee. The application is no longer aiming for exactly-once delivery, which is usually impractical across separate systems. It aims for at-least-once delivery combined with idempotent consumers. A message may be delivered more than once, but it must not be lost after the database transaction commits.

A small, useful schema

Keep the outbox explicit and boring. It is operational infrastructure, so it should be easy to inspect when something goes wrong.

CREATE TABLE outbox_messages (
    id CHAR(36) PRIMARY KEY,
    topic VARCHAR(100) NOT NULL,
    payload JSON NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    processed_at TIMESTAMP NULL,
    attempts INT NOT NULL DEFAULT 0,
    last_error TEXT NULL
);

CREATE INDEX outbox_pending_idx
    ON outbox_messages (processed_at, created_at);

The message ID is important. It gives consumers a stable idempotency key and gives operators a precise identifier for tracing failures. The payload should contain enough context for the consumer to act without immediately needing a fragile callback into the originating service.

Do not treat the outbox as a permanent event archive unless that is a conscious requirement. A routine retention policy can remove successfully processed rows after the period needed for diagnosis and replay.

Writing the business change in PHP

The important part is not a framework feature; it is transaction scope. The business write and outbox insert must use the same database connection and occur before the same commit.

$pdo->beginTransaction();

try {
    $orderId = '...';       // Generated by the application
    $messageId = '...';     // A unique, stable message ID

    $order = $pdo->prepare(
        'INSERT INTO orders (id, customer_id, status) VALUES (?, ?, ?)'
    );
    $order->execute([$orderId, $customerId, 'placed']);

    $outbox = $pdo->prepare(
        'INSERT INTO outbox_messages (id, topic, payload)
         VALUES (?, ?, CAST(? AS JSON))'
    );
    $outbox->execute([
        $messageId,
        'orders.placed',
        json_encode([
            'event_id' => $messageId,
            'order_id' => $orderId,
            'customer_id' => $customerId,
        ], JSON_THROW_ON_ERROR),
    ]);

    $pdo->commit();
} catch (Throwable $error) {
    if ($pdo->inTransaction()) {
        $pdo->rollBack();
    }

    throw $error;
}

Notice what is absent: no broker call inside the transaction. Calling a remote service while holding database locks makes transactions slower and less predictable. More importantly, it still cannot make the remote publish and database commit atomic.

Delivering messages safely

A worker can poll for pending messages, claim a small batch, publish each event, and mark each successful one as processed. The exact SQL depends on the database engine, especially when multiple workers run concurrently. The goal is always the same: prevent two workers from processing the same row at the same time, while avoiding long-held locks during network calls.

A practical design adds claim fields such as locked_at and locked_by. A worker atomically claims eligible rows, commits that claim, publishes outside the claim transaction, then records success or failure. Claims need an expiry so a message becomes eligible again if a worker dies mid-flight.

• Use a bounded batch size so one slow integration does not monopolize the worker.
• Increment attempts and store a safe diagnostic error after a failed publish.
• Apply backoff for repeated failures instead of retrying a broken destination in a tight loop.
• Alert on old unprocessed messages and unusually high attempt counts.
• Keep publishing code separate from domain write code; this makes failures easier to test and operate.

A worker must assume this sequence is possible: publish succeeds, then the process dies before processed_at is updated. The message will be sent again after the claim expires. That is not a flaw in the pattern; it is the expected reason consumers must be idempotent.

Idempotency is the other half

Consumers should record the event ID before or while applying their own side effect. For example, a service can insert the event ID into a table protected by a unique constraint. If a duplicate arrives, the constraint indicates it has already been handled.

For an external API, use its idempotency mechanism when available, keyed by the outbox message ID. If it has no such mechanism, persist enough local state to avoid repeating the irreversible action. Sending an email twice or creating a duplicate subscription is rarely fixed by merely retrying harder.

Also make event semantics clear. An event named orders.placed should describe a completed fact, not an instruction whose interpretation varies by consumer. Include a version in the payload when it may evolve, and keep consumers tolerant of additive fields.

Common shortcuts that quietly fail

Some teams write the database row, commit, and then “retry publishing later” from application memory. A restart erases that retry queue. Others publish before committing and hope rollbacks are rare. Rare inconsistencies are still inconsistencies, and they are often the hardest ones to reconcile.

Another mistake is marking an outbox row processed before the remote call completes. That trades duplicates for lost messages. The safer trade is the reverse: publish first, then mark success, accepting duplicates and designing for them.

Make reliability visible

The outbox pattern is not just code; it is an operating model. Track pending count, age of the oldest pending message, delivery failures, and processing throughput. Provide a controlled way to replay a message after fixing a consumer or destination. Log message IDs consistently across the API request, worker, and integration client.

Transactional outbox does not make distributed systems simple. It gives uncertainty a durable place to live, where it can be retried, observed, and repaired. For PHP integrations that must survive crashes, timeouts, and deployments, that is a much stronger foundation than hoping two independent writes happen in the right order.