Download the PHP package gpalyan/laravel-outbox without Composer

Laravel package implementing the Transactional Outbox / Inbox patterns. Broker-agnostic: ship messages to any transport (NATS, Kafka, RabbitMQ, SQS, HTTP webhook — anything you can call publish() on).

Contents

• Delivery semantics
• Requirements
• Installation
• Configuration
• Outbox — publishing messages
  • 1. Write to the outbox inside your DB transaction
  • 2. Implement OutboxPublisherInterface for your broker
  • 3. Bind it in the service container
  • 4. Schedule the publisher worker
• Inbox — receiving messages
  • 1. From your broker subscriber, fire MessageConsumed
  • 2. Implement a handler per channel
  • 3. Bind channel → handler in the container
  • 4. Schedule the inbox worker
• Pruning old rows
• How it works
• Public surface
• Client responsibilities

Delivery semantics

The package gives you at-least-once delivery to the broker plus idempotent storage on both sides keyed on a caller-supplied deduplication_key. Composed together, this is what is commonly called effectively-exactly-once:

• Outbox side. OutboxMessage::store() is a firstOrCreate keyed on the deduplicationKey you pass. Calling it twice with the same key inside a retried HTTP request or a retried job stores one row, not two.
• Publisher worker. Keeps retrying with exponential backoff until your OutboxPublisherInterface::publish() returns without throwing. If the broker accepts the message but the ack is lost, the worker will publish again — downstream must be idempotent. This is fundamental to any outbox; the package does not paper over it.
• Inbox side. InboxMessage::store() is also firstOrCreate on the key you pass — typically the broker message id. Re-deliveries of the same message land on the same row, the handler runs once.

True exactly-once delivery to a remote broker is impossible (FLP, two-generals); don't promise it. What you can promise to downstream consumers is effectively-exactly-once processing of each logical message, which is what this package implements.

The deduplication key is yours, by design. The identity of a logical message — "is this the same event or a new one?" — is domain knowledge only the caller has; the package cannot infer it and does not try. You pass an explicit deduplicationKey (e.g. order.created:42, or order.payout:42:attempt-2 when a second payout is intended). Make it stable for the same logical event and distinct for genuinely different ones.

If you want content-addressed dedup (one row per unique payload), opt in explicitly with OutboxMessage::hashPayload($payload) as the key — but note it only holds if the payload is canonical (no timestamps / random fields), otherwise duplicates hash differently and won't dedup.

Requirements

• PHP 8.4+
• Laravel 12 / 13

Installation

Publish config and migrations:

Configuration

Outbox — publishing messages

1. Write to the outbox inside your DB transaction

Batch insert (skips Eloquent events, useful for bulk producers). Each item is an OutboxDraft — the deduplication key is a required constructor argument, so it cannot be silently omitted for any message in the batch:

Duplicate keys inside a single batch (or against rows already stored) are skipped by the unique index — no need to pre-check the array yourself.

2. Implement OutboxPublisherInterface for your broker

Below is a complete working example using RabbitMQ via php-amqplib/php-amqplib. Replace with your broker SDK; the contract is the same: take an OutboxMessage, publish it, throw on failure.

Route table lives in your own config:

3. Bind it in the service container

4. Schedule the publisher worker

Inbox — receiving messages

1. From your broker subscriber, fire MessageConsumed

The package does not subscribe to any broker. You bring your own subscriber (a long-running artisan command, a daemon, a worker subscribed to push notifications — whatever fits your broker). For each message received, fire the package event.

A complete RabbitMQ subscriber as an artisan command:

Run one process per (queue, channel) pair under supervisor / systemd:

The package registers OnMessageConsumed to this event automatically. The listener stores the message in inbox_messages (idempotent on the deduplicationKey you supply — use the broker message id so broker re-deliveries dedup).

Synchronicity contract — important.

event(new MessageConsumed(...)) invokes the listener synchronously, in the same PHP process and call stack as your subscriber. The listener performs a DB write before event() returns. Implications:

• Ack the broker only after event() returns. If you ack first and event() then throws (DB unavailable, constraint failure, etc.), the inbox row is not persisted but the broker considers the message delivered — silent loss. The correct order is: receive → fire event() → on success, ack; on exception, nack/let the broker redeliver. This is what makes the system at-least-once end-to-end.
• Do not wrap the listener in Event::fake() in tests unless you re-fake selectively. Event::fake() with no arguments swallows all events, including MessageConsumed, and your inbox table stays empty. Use Event::fake([SomeUnrelatedEvent::class]) to fake specific events only, or assert against the inbox row directly.
• Do not queue the listener. If you ever make OnMessageConsumed implement ShouldQueue, the listener becomes async — event() returns before the DB write, you can ack the broker and then lose the message if the queue or DB fails. The default registration is intentionally synchronous.

2. Implement a handler per channel

3. Bind channel → handler in the container

The key passed to bind() must match the channel you put into MessageConsumed.

4. Schedule the inbox worker

Pruning old rows

prune_after_days in config controls the cutoff. Only successfully terminated rows are pruned — SENT on the outbox side, PROCESSED on the inbox side. FAILED rows are kept indefinitely.

Why FAILED rows are never auto-pruned

A FAILED row means the package exhausted retries and gave up. Two cases:

• Outbox FAILED — the publisher could not hand the message off to the broker at all (broker unavailable, route misconfigured, payload rejected). The message never reached any broker DLQ — this is your application-side dead letter.
• Inbox FAILED — your handler kept throwing past max_attempts. The message was received from the broker but cannot be processed locally. Again, a dead letter at the application boundary.

In both cases the row is the only surviving evidence of a lost business event. Auto-pruning it silently erases problems that need human eyes — broken routes, bad payloads, handler bugs. So the package keeps them.

How it works

Both sides use exponential backoff on failure with configurable max attempts. Stuck in-progress rows (worker crashed mid-flight) are returned to pending after the configured deadline.

Public surface

Client responsibilities