Download the PHP package urfysoft/transactional-outbox without Composer

Transactional Outbox Pattern for Laravel Microservices

Complete Transactional Outbox implementation for reliable communication between microservices.

Installation

Publish assets

This command copies:

• config/transactional-outbox.php
• database/migrations/*create_outbox_messages_table.php
• database/migrations/*create_inbox_messages_table.php

Run the migrations after publishing:

Configuration

Key settings live in config/transactional-outbox.php.

• Service identity & Sanctum ability
  • service_name: name announced in outbound headers.
  • sanctum.required_ability: ability that incoming Sanctum tokens must possess.
• Headers
  • Override header names or the prefix (default X-) via the headers array.
• Destinations
  • Map logical service names to endpoints inside the services array.
• Driver
  • Choose the message broker driver (http, kafka, rabbitmq when implemented).
• Processing
  • Control batch size, retry limits, and throttling.
• Inbox handlers
  • Register classes implementing Urfysoft\TransactionalOutbox\Contracts\InboxEventHandler under inbox.handlers.

Example handler:

Register the class in config/transactional-outbox.php or at runtime:

Sanctum setup

The package expects Laravel Sanctum to be installed and configured.

Issue tokens for upstream services with the configured ability (default transactional-outbox):

Architecture Overview

Outbox Pattern (Sending Messages)

1. Business logic and an outbox message are persisted in the same database transaction
2. A background worker reads the outbox table and publishes to the message broker
3. Messages are marked as published once delivery succeeds
4. Failed messages are automatically retried

Inbox Pattern (Receiving Messages)

1. Messages arrive via HTTP webhooks or a broker consumer
2. Each message is stored in the inbox table for idempotency (duplicate detection)
3. A background worker processes inbox messages
4. Business logic runs in a transaction that also updates the message status

Usage Examples

Sending Messages to Other Services

Single destination

Multiple destinations

Receiving Messages from Other Services

Event handler registration

Inside MessageBrokerServiceProvider:

Webhook endpoint

Other services POST to:

Message Broker Options

HTTP (Default)

• Simple REST API calls
• No additional infrastructure required
• Great for small/medium deployments

Kafka

Set MESSAGE_BROKER_DRIVER=kafka

RabbitMQ

Set MESSAGE_BROKER_DRIVER=rabbitmq

Running the System

Start the scheduler (required)

Manual processing

Configuration Tips

• Header names: customize transactional-outbox.headers to redefine which headers carry the message id, source service, event type, or to change the prefix used when collecting custom metadata.
• Inbox handlers: list handler classes inside transactional-outbox.inbox.handlers. Each class must implement Urfysoft\TransactionalOutbox\Contracts\InboxEventHandler (define eventType() and handle()).
• Runtime registration: handlers can also be registered anywhere via the facade:

Monitoring

Key Capabilities

✅ Atomicity: Business logic and messages live in the same transaction\ ✅ Reliability: No data loss even when the broker is down\ ✅ Idempotency: Duplicate messages are automatically detected\ ✅ Retry logic: Failed deliveries are retried automatically\ ✅ Multi-broker: HTTP, Kafka, RabbitMQ drivers\ ✅ Monitoring: Track message statuses and errors\ ✅ Scalability: Batch processing support

Best Practices

1. Always propagate a correlation ID for request tracing
2. Keep payloads small—send references instead of full objects
3. Monitor failed messages and set up alerts
4. Clean up regularly to remove processed records
5. Test idempotency to ensure handlers tolerate duplicates
6. Use a dead-letter queue after exhausting retries
7. Version your events—include a version in event_type

Troubleshooting

Messages are not processed:

• Ensure the scheduler is running: php artisan schedule:work
• Inspect message statuses in the database
• Check logs: tail -f storage/logs/laravel.log

Duplicate messages:

• The Inbox pattern handles duplicates automatically
• Verify message_id uniqueness

Failed messages:

• Inspect the last_error column
• Use the retry command: php artisan outbox:process --retry
• Confirm the destination service is reachable

Advanced Topic: Saga Pattern

Combine Transactional Outbox with the Saga pattern for distributed transactions: