PHPackages                             xerxes/laravel-rabbitmq-communication - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. xerxes/laravel-rabbitmq-communication

ActiveLibrary[Queues & Workers](/categories/queues)

xerxes/laravel-rabbitmq-communication
=====================================

A Laravel package for RabbitMQ messaging with outbox pattern, dead letter queues, and automatic retry mechanisms

v2.1.0(4mo ago)079MITPHPPHP ^8.1

Since Jan 8Pushed 4mo agoCompare

[ Source](https://github.com/xerxes-on/mq-communication)[ Packagist](https://packagist.org/packages/xerxes/laravel-rabbitmq-communication)[ RSS](/packages/xerxes-laravel-rabbitmq-communication/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (11)Versions (2)Used By (0)

Laravel RabbitMQ Communication
==============================

[](#laravel-rabbitmq-communication)

[![Latest Version](https://camo.githubusercontent.com/9f7d881223a0ce4d778f2b84dc71d93f4af226394e5a55bdab5cac28ee2c5495/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7865727865732f6c61726176656c2d7261626269746d712d636f6d6d756e69636174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/xerxes/laravel-rabbitmq-communication)[![License](https://camo.githubusercontent.com/a8879222666f9a7ede63b0accef9f70202d3c63cc3bb04ca66e3f0a7c11d6e6f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7865727865732f6c61726176656c2d7261626269746d712d636f6d6d756e69636174696f6e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

A Laravel package for RabbitMQ messaging with support for the outbox pattern, event consumers, dead letter queues, and automatic retry mechanisms.

Features
--------

[](#features)

- **Direct Publish with Outbox Fallback** - Messages are published directly; if RabbitMQ is unavailable, they're stored for later retry
- **Event Consumers** - Consume messages from multiple queues with configurable handlers
- **Dead Letter Queue (DLQ)** - Automatic retry with exponential backoff, failed messages go to DLQ
- **Type-Safe Enums** - PHP 8.1+ enums for status and mode handling
- **Fully Configurable** - Environment-based configuration for all settings

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 9, 10, 11, or 12
- RabbitMQ Server
- ext-json

Installation
------------

[](#installation)

```
composer require xerxes/laravel-rabbitmq-communication
```

Publish the configuration:

```
php artisan vendor:publish --tag=laravel-rabbitmq-communication-config
```

Run migrations:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

### Environment Variables

[](#environment-variables)

```
# Connection Settings
RABBITMQ_HOST=127.0.0.1
RABBITMQ_PORT=5672
RABBITMQ_USER=guest
RABBITMQ_PASS=guest
RABBITMQ_VHOST=/

# Outbox Pattern (always enabled as fallback)
RABBITMQ_OUTBOX_CONNECTION=outbox

# Dead Letter Queue
RABBITMQ_DLQ_ENABLED=true
RABBITMQ_DLQ_EXCHANGE=dlx.failed
RABBITMQ_DLQ_MAX_RETRIES=3

# Consumer Settings
RABBITMQ_CONSUMER_MODE=sync
RABBITMQ_CONSUMER_PREFETCH=10
RABBITMQ_LOG_CHANNEL=stack
```

Publishing Messages
-------------------

[](#publishing-messages)

### Basic Publishing

[](#basic-publishing)

```
use Xerxes\RabbitMQ\RabbitMQ;

app(RabbitMQ::class)
    ->message()
    ->viaExchange('my.exchange')
    ->route('my.routing.key')
    ->withPayload(['event' => 'user.created', 'data' => [...]])
    ->persistent()
    ->publish();
```

### Publishing with Headers

[](#publishing-with-headers)

```
app(RabbitMQ::class)
    ->message()
    ->viaExchange('my.exchange')
    ->route('my.routing.key')
    ->withPayload($payload)
    ->withHeaders(['x-custom-header' => 'value'])
    ->persistent()
    ->publish();
```

### Outbox Pattern (Guaranteed Delivery)

[](#outbox-pattern-guaranteed-delivery)

The outbox pattern is always enabled as an automatic fallback and cannot be disabled. Messages follow this flow:

1. **Try direct publish** - Message is sent immediately to RabbitMQ
2. **On failure** - Message is automatically stored in the database outbox table
3. **Outbox worker** - Processes pending messages and retries publishing

```
app(RabbitMQ::class)
    ->message()
    ->viaExchange('my.exchange')
    ->route('my.routing.key')
    ->withPayload($payload)
    ->publish();
```

Process outbox messages:

```
php artisan outbox:work
```

### Using Laravel Events

[](#using-laravel-events)

Implement the `ShouldPublish` interface to automatically publish events:

```
use Xerxes\RabbitMQ\Support\ShouldPublish;

class UserCreated implements ShouldPublish
{
    public string $exchange = 'user.events';

    public function __construct(
        public User $user
    ) {}

    public function routingKey(): string
    {
        return 'user.created';
    }
}

// Dispatch normally - automatically published to RabbitMQ
event(new UserCreated($user));
```

Consuming Messages
------------------

[](#consuming-messages)

### Configuration

[](#configuration-1)

Define event consumers in `config/rabbitmq.php`:

```
'event-consumers' => [
    [
        'exchange' => 'user.events',
        'exchange_type' => 'topic',
        'routing_key' => 'user.#',
        'handler' => [\App\Handlers\UserHandler::class, 'handle'],
        'queue' => 'my-app.users',
    ],
],
```

### Handler Class

[](#handler-class)

Your handler should implement the `MessageHandler` interface:

```
use Xerxes\RabbitMQ\Contracts\MessageHandler;

class UserHandler implements MessageHandler
{
    public function handle(array $payload, ?string $routingKey = null): void
    {
        // Process the message
        Log::info('Processing user event', [
            'routing_key' => $routingKey,
            'payload' => $payload,
        ]);
    }
}
```

### Running the Consumer

[](#running-the-consumer)

```
php artisan rabbitmq:consume-events
```

### Consumer Modes

[](#consumer-modes)

Configure how consumed events are dispatched:

- **sync**: Events fired synchronously. Errors stop the consumer (unless DLQ is enabled).
- **kind-sync**: Events fired synchronously. Errors are logged but don't stop the consumer.
- **job**: Events dispatched via Laravel queue jobs.

### Message Acknowledgment

[](#message-acknowledgment)

Message acknowledgment is always required and cannot be disabled:

- **On success**: Message is acknowledged and removed from the queue
- **On failure**: Message is rejected and requeued for retry
- **With DLQ enabled**: After max retries, message is moved to the dead letter queue

Dead Letter Queue (DLQ)
-----------------------

[](#dead-letter-queue-dlq)

### How It Works

[](#how-it-works)

1. Message fails processing
2. Republished to retry queue with delay
3. After TTL, routed back to original queue
4. After max retries (default: 3), moved to dead letter queue
5. Failed messages can be manually reprocessed

### Retry Flow

[](#retry-flow)

```
Message fails → Retry Queue (5s delay) → Original Queue
     ↓ fails again
Retry Queue (30s delay) → Original Queue
     ↓ fails again
Retry Queue (2min delay) → Original Queue
     ↓ fails again (max retries exceeded)
Dead Letter Queue (.dlq)

```

### Reprocessing Failed Messages

[](#reprocessing-failed-messages)

```
# Reprocess up to 100 messages
php artisan rabbitmq:reprocess-dlq my-app.orders

# Limit the number
php artisan rabbitmq:reprocess-dlq my-app.orders --limit=50

# Dry run
php artisan rabbitmq:reprocess-dlq my-app.orders --dry-run
```

Available Commands
------------------

[](#available-commands)

CommandDescription`rabbitmq:consume-events`Start consuming messages from configured queues`outbox:work`Run outbox worker (continuous)`outbox:process`Process outbox messages once`rabbitmq:declare-exchanges`Declare configured exchanges`rabbitmq:test-connection`Test RabbitMQ connection`rabbitmq:reprocess-dlq {queue}`Reprocess messages from dead letter queueTesting
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance77

Regular maintenance activity

Popularity12

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

124d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a478360844423217c81122d0fa60a21d962022900ae1c642a9aff16a1518260a?d=identicon)[xerxes-on](/maintainers/xerxes-on)

---

Tags

laravelevent-drivenrabbitmqmessagingoutbox-patterndead-letter-queue

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/xerxes-laravel-rabbitmq-communication/health.svg)

```
[![Health](https://phpackages.com/badges/xerxes-laravel-rabbitmq-communication/health.svg)](https://phpackages.com/packages/xerxes-laravel-rabbitmq-communication)
```

###  Alternatives

[nuwber/rabbitevents

The Nuwber RabbitEvents package

120515.8k3](/packages/nuwber-rabbitevents)[bschmitt/laravel-amqp

AMQP wrapper for Laravel and Lumen to publish and consume messages

2752.3M7](/packages/bschmitt-laravel-amqp)[convenia/pigeon

3233.0k](/packages/convenia-pigeon)[iamfarhad/laravel-rabbitmq

A robust RabbitMQ driver for Laravel Queue with advanced message queuing, reliable delivery, and high-performance async processing capabilities

3215.6k](/packages/iamfarhad-laravel-rabbitmq)[sokanacademy/laravel-fluent-rabbitmq

integrate rabbitmq in a laravel application

323.2k](/packages/sokanacademy-laravel-fluent-rabbitmq)[kunalvarma05/laravel-rabbitmq

Work with RabbitMQ in Laravel.

1853.7k](/packages/kunalvarma05-laravel-rabbitmq)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)