Download the PHP package bugfix666/laravel-outbox without Composer

Laravel Outbox

[]()

Transactional Outbox pattern implementation for Laravel 12+ (PHP 8.4+).
Guarantees atomicity and reliable event delivery in distributed systems, especially fintech, e‑commerce, and microservices.

📊 Comparison with Existing Solutions

There are several open‑source implementations of the Transactional Outbox pattern for Laravel. Here’s how laravel-outbox compares to them:

🚀 Why This Package Stands Out

1. Cutting‑Edge Stack – Built specifically for PHP 8.4+ and Laravel 12+, leveraging the latest language features for cleaner, safer, and more maintainable code.

2. Production‑Ready – Unlike some alternatives that are still in beta, this package is fully tested (15+ unit and feature tests) and ready for mission‑critical applications.

3. Dead Letter Queue (DLQ) – Failed messages after all retries are not lost. They remain in the outbox table for inspection and manual intervention – essential for fintech and reliability‑first systems.

4. Explicit Control, No Magic – Unlike packages that automatically intercept all events/jobs, this package gives you full control over what and when to publish. No surprises, easier debugging, and predictable behavior.

5. Built‑in Monitoring – The OutboxMessageProcessed and OutboxMessageFailed events allow seamless integration with logging, metrics (Prometheus, StatsD), and alerting.

6. Strict Typing & Modern Practices – Readonly classes, typed properties, constructor property promotion, and console command attributes make the code self‑documenting and robust.

If you need a reliable, modern, and transparent outbox implementation for your fintech or distributed system – this package is the best choice among all existing open‑source solutions.

📦 Features

• ✅ Atomic persistence – business data + outbox record in a single DB transaction.
• ✅ Reliable background processing – worker with locking, batch processing, and retries.
• ✅ Flexible publishers – log, queue, or your own (Kafka, RabbitMQ, SNS, etc.).
• ✅ Built‑in retry logic – exponential backoff (configurable attempts & delay).
• ✅ Monitoring – events for processed/failed messages; easy to integrate with logging or metrics.
• ✅ Cleanup – automated purging of old processed messages.
• ✅ Modern PHP 8.4+ – typed properties, readonly classes, enums, constructor promotion.
• ✅ Laravel 12+ ready – uses new attribute‑based console commands.

🔧 Requirements

• PHP 8.4 or higher
• Laravel 12.0 or higher
• Database that supports transactions (MySQL, PostgreSQL, SQLite, etc.)

📥 Installation

🚀 Setup

Publish the configuration and migration files:

Run the migration to create the outbox_messages table:

⚙️ Configuration

The config file config/outbox.php allows you to tailor the package to your needs:

Set your preferred publisher in .env:

💡 Basic Usage

1. Store an outbox message inside a transaction

2. Run the worker

Start the outbox processor (should be supervised in production):

You can override batch size on the fly:

3. Clean up old processed messages

Schedule the cleanup command to run daily (in routes/console.php):

Or run manually:

🔌 Custom Publisher

By default, the package logs events. To send events to a real broker, create a class that implements Bugfix666\LaravelOutbox\Contracts\OutboxPublisher:

Then set OUTBOX_PUBLISHER=App\Publishers\KafkaPublisher in your .env.

Tip: For RabbitMQ, use php-amqplib; for AWS SNS, use the Laravel SNS facade.

🧩 Monitoring and Events

The package fires two events that you can listen to:

• Bugfix666\LaravelOutbox\Events\OutboxMessageProcessed
• Bugfix666\LaravelOutbox\Events\OutboxMessageFailed

Example listener:

Register your listener in EventServiceProvider.

🔄 Retry Logic

When publishing fails, the worker increments the attempts counter and sets available_at to now() + delay_seconds. The next run will only pick messages where available_at is in the past, giving the broker time to recover.

After max_attempts failures, the message remains unprocessed but is considered failed – you can handle it manually or set up an alert.

🧪 Testing

The package is fully testable. You can mock the publisher and assert that messages are stored and processed correctly.

Example test:

📊 Performance Considerations

• Indexes – The migration includes indexes on (processed_at, created_at), aggregate_type/aggregate_id, and available_at to keep queries fast.
• Batch size – Tune batch_size according to your workload. Larger batches reduce DB round‑trips but increase memory usage.
• Partitioning – For extremely high volume, consider table partitioning by created_at (e.g., daily) to keep the active set small.
• Locking – The worker uses FOR UPDATE to prevent double‑processing. Ensure your database supports row‑level locking.

🛠 Supervisor Configuration

For production, keep the worker running with Supervisor:

📖 Full Documentation

• Transactional Outbox Pattern – Martin Fowler
• Laravel 12 Documentation

🤝 Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

Please ensure that your code passes the existing tests and is well‑documented.

📝 License

This package is open‑source software licensed under the MIT license.

💬 Support

For questions, bug reports, or feature requests, please open an issue on GitHub.

Happy coding, and may your events always be delivered! 🚀