Weave Code
Message Outbox For Illuminate Laravel Package
eventsauce/message-outbox-for-illuminate
A Laravel/Illuminate outbox for EventSauce that persists domain messages transactionally alongside your business data, then relays them to consumers, avoiding dual-write problems and helping guarantee reliable, at-least-once event delivery.
Message Outbox Pattern implementation for Illuminate
Frequently asked questions about Message Outbox For Illuminate
- What is the transactional outbox pattern and how does this package implement it in Laravel?
- The package writes EventSauce domain messages into an outbox table using Illuminate's database layer, inside the same transaction that persists your aggregate. Because both writes commit atomically, a crash after commit cannot lose the message or produce a phantom event. A separate relay drains the outbox afterward and publishes to your broker or queue with at-least-once semantics. That replaces the common Laravel anti-pattern of dispatching jobs inside a transaction or from model observers.
- How do I install eventsauce/message-outbox-for-illuminate with Composer?
- Run composer require eventsauce/message-outbox-for-illuminate and let Laravel's package discovery register the service provider. You will still need the outbox table schema, a message serializer, and a supervised relay process, so the composer line is the smallest part of the integration. The package is a thin adapter, so plan for the relay and its observability as part of the same deliverable.
- Which Laravel and PHP versions does eventsauce/message-outbox-for-illuminate support?
- Version constraints come from the EventSauce monorepo, because this repository is a read-only subtree split and its tags mirror upstream tags. That means the illuminate/* and PHP requirements are not documented in this repository, so check the composer.json of the specific tag before committing. Confirm an explicit Laravel 11 or 12 support statement from the upstream release you plan to use, and verify it rather than assuming.
- Does the package ship a publishable migration for the outbox table?
- Treat schema ownership as something to confirm before you design the relay, since usage guidance lives in the EventSauce documentation rather than in this repository. If no publishable migration is provided, you own the outbox table definition, its indexes, and any status or timestamp columns the relay relies on. Pin that down early, because the relay's locking strategy depends on the table shape.
- Is the relay an Artisan command or a queued job in the EventSauce outbox?
- The outbox abstraction leaves the relay to you: an Artisan command or queue worker running under a supervisor, reading unpublished rows and handing them to your dispatcher or broker. This package provides persistence and container bindings, not a turnkey relay daemon, so budget time to build and operate one. Also decide who owns retries, dead-letter handling, and relay metrics.
- How does the outbox relay handle concurrent workers and per-aggregate message ordering?
- Concurrency control is a design decision you make on your outbox table, not something the adapter hides. On PostgreSQL you can claim rows with FOR UPDATE SKIP LOCKED so multiple relay processes do not double-publish, and MySQL 8+ supports similar patterns while older engines make it harder. Per-aggregate ordering needs an explicit ordering key or sequence column in your query, so verify it against your engine before committing.
- Can I use this package without EventSauce, or with a different event sourcing library?
- It is the Illuminate binding for EventSauce's MessageOutbox abstraction, so it expects EventSauce contracts such as Message and MessageDispatcher. If your team uses another event-sourcing library, or the consumer can join the transaction directly, the package adds a dependency without removing a failure mode. The pattern itself is portable, but this specific package is not library-agnostic.
- Is eventsauce/message-outbox-for-illuminate production ready?
- The architecture is well understood and correct, but this split repository has no stars, no dependents, and no public corpus of production war stories, tutorials, or Stack Overflow answers. It is also a read-only subtree split of the EventSauce monorepo with no issue tracker and no PR flow, so fixes require an upstream release or a fork. That is a bus-factor and support consideration rather than evidence of poor quality, but plan for it explicitly.
- How do I test the transactional outbox in a Laravel test suite?
- Wrap an aggregate command in a database transaction in your test, assert both the aggregate state and the outbox row are visible after commit, then assert nothing is written when the transaction rolls back. Seed rows directly into the outbox table to test the relay in isolation, and keep the test database refreshed so relay behavior stays deterministic. Include a duplicate-delivery test, since the guarantee is at-least-once rather than exactly-once.
- Do I need to prune the outbox table, and what are the alternatives to this package?
- Retention and pruning are entirely on you unless you build them into your relay, so plan a delete or archive job for published rows with indexes that keep it cheap. As an alternative, a competent engineer can hand-roll the transactional outbox shape in a day or two, and adopting the pattern without the package is a legitimate outcome. The package mainly buys EventSauce contract compatibility and familiar Laravel service-container bindings.
Weaver
How can I help you explore Laravel packages today?