Download the PHP package nuwber/rabbitevents without Composer

RabbitEvents

[!IMPORTANT] Repository & Package Migration Announcement

RabbitEvents has moved to its own dedicated organization!

• GitHub Repository: github.com/rabbitevents/rabbitevents (formerly nuwber/rabbitevents)
• Composer Package: rabbitevents/rabbitevents (starting from version 10.0)

Please update your composer.json to require rabbitevents/rabbitevents:^10.0. All PHP classes and namespaces (RabbitEvents\...) remain identical, so no application code changes are required.

Let's imagine a use case: a User made a payment. You need to handle this payment, register the user, send him emails, send analytics data to your analysis system, and so on. The modern infrastructure requires you to create microservices that do their specific job and only it: one handles payments, one is for user management, one is the mailing system, one is for analysis. How to let all of them know that a payment succeeded and handle this message? The answer is "To use RabbitEvents".

RabbitEvents helps you publish an event and handle it seamlessly in other applications across your microservice ecosystem.

Demo

Table of Contents

1. Installation via Composer
   • Configuration
2. Upgrade from 9.x to 10.x
3. Quick Start
   • Publishing Events
   • Listening for Events
4. Reliability & Guarantees (Zero-DB Architecture)
   • Message IDs & Observability
   • Idempotency & Deduplication
   • Dead Letter Queue (DLQ) & Failed Message Management
   • Transactional Publishing (ShouldPublishAfterCommit)
   • Distributed Tracing & Context Propagation
5. Listeners & Payloads
6. Custom Serializers
7. Extensions & Ecosystem
8. Examples
9. Speeding up RabbitEvents
10. Testing
11. Non-standard use
12. License

Installation via Composer

You can use Composer to install RabbitEvents into your Laravel project:

Configuration

After installing RabbitEvents, publish its configuration file and service provider using the rabbitevents:install command:

This installs config/rabbitevents.php and app/Providers/RabbitEventsServiceProvider.php.

Upgrade from 9.x to 10.x

Breaking Changes & Requirements

1. Composer Package Name Changed

RabbitEvents is now an independent project maintained under rabbitevents/rabbitevents. To upgrade, replace nuwber/rabbitevents in your composer.json or run:

Zero Namespace Changes: The PHP namespace remains RabbitEvents\.... You do not need to change any use statements or event classes in your codebase.

2. PHP 8.2+ and Laravel 11+ Required

RabbitEvents 10.x requires PHP 8.2 or greater and Laravel 11.0 or greater. Distributed tracing automatically utilizes Laravel's native Context facade.

3. Return Value of publish()

The publish() helper now returns the generated string Message ID (UUIDv4) or null instead of void:

4. Existing RabbitMQ Queues & Dead Letter Exchange (DLX)

In 10.x, Dead Letter Queue routing is enabled by default (x-dead-letter-exchange: rabbitevents.dlx). Because RabbitMQ queue declaration arguments are immutable:

• If you have existing queues created by 9.x, RabbitMQ will reject the new declaration with a PRECONDITION_FAILED error.
• To upgrade smoothly, either recreate the worker queues (delete them so RabbitEvents redeclares them with DLX) or disable DLX in config/rabbitevents.php by setting 'dlx.enabled' => false (or RABBITEVENTS_DLX_ENABLED=false).

5. Removed rabbitevents:restart Command

The deprecated rabbitevents:restart command has been removed. Use your process supervisor (Supervisor, Kubernetes, Docker) to restart listener workers gracefully.

What's New in 10.0

• Out-of-the-Box Deduplication: Automatically drops duplicate messages using an in-memory ring buffer (InMemoryDeduplicator) without needing MySQL or Redis.
• Dead Letter Queue (DLQ) & CLI Management: Failed messages sitting in {queue}.failed can be inspected and managed with php artisan rabbitevents:failed, retry, forget, and flush.
• Transactional Publishing (afterCommit): Publish events only after database transactions commit via ShouldPublishAfterCommit or $afterCommit = true.
• Distributed Tracing: Seamlessly propagates Laravel 11 Context data across services via trace_context headers.

Quick Start

1. Publishing Events

Method A: Using the publish() helper

The quickest way to dispatch an event from anywhere in your application:

Method B: Using an Event Class

Define a dedicated event class implementing ShouldPublish:

Dispatch it just like standard Laravel events:

2. Listening for Events

Method A: Using PHP Attributes (Recommended)

Define a listener and tag it with #[Listener]:

Method B: Using RabbitEventsServiceProvider

Register listeners explicitly in app/Providers/RabbitEventsServiceProvider.php:

Start the Worker

Run the listener worker from your terminal or process manager (Supervisor, Docker, Kubernetes):

Or listen to multiple events or wildcard patterns:

Reliability & Guarantees (Zero-DB Architecture)

RabbitEvents is designed for microservice environments where services should remain isolated and autonomous. It provides enterprise-level reliability without requiring MySQL tables, Redis, or database migrations.

Message IDs & Observability

Every published event automatically receives a unique RFC 4122 UUIDv4 message_id.

Listener worker console logs display the message ID and execution time in real-time:

Idempotency & Deduplication

In distributed systems, network retries can cause duplicate message deliveries. RabbitEvents prevents duplicate execution:

• In-Memory Ring Buffer (Default): Automatically remembers the last N processed message IDs in the current worker process's memory. Requires zero dependencies. Note: Because it is per-process and lost on worker restart, it protects against redelivery to the same worker after all listeners have succeeded. For cross-worker or persistent deduplication, use the RabbitMQ plugin or ensure your listeners are idempotent.
• RabbitMQ Message Deduplication Plugin: For broker-level deduplication across multiple horizontally scaled workers using the rabbitmq-message-deduplication plugin.

Configure in config/rabbitevents.php:

Dead Letter Queue (DLQ) & Failed Message Management

When an event listener fails and exhausts all retry attempts (--tries=3), RabbitEvents automatically stores the message in {queue}.failed.

The failed message retains its original payload, routing key, timestamp, and diagnostic headers (x-exception-message, x-exception-class, x-exception-trace, x-failed-at, x-original-routing-key, x-listener, trace_context).

You can inspect and manage failed messages with built-in Artisan commands:

[!TIP] Zero-Downtime Coexistence with RabbitEvents 9.x Existing queues declared under RabbitEvents 9.x continue working seamlessly without requiring manual queue deletion or migration. If an existing queue lacks RabbitMQ DLX arguments, RabbitEvents 10.x logs a warning and automatically activates application-level dead-letter routing to deliver failed messages to {queue}.failed.

Transactional Publishing (afterCommit)

Prevent race conditions by ensuring events are published only after database transactions commit. You can implement ShouldPublishAfterCommit, set $afterCommit = true, or call ->afterCommit():

Distributed Tracing & Context Propagation

Laravel 11+ Context data is automatically serialized into AMQP trace_context headers on publish and hydrated on the listener side, allowing seamless distributed tracing:

Listeners & Payloads

How the payload is passed to your listener depends on the serialization format:

JSON (Default): The payload is decoded as an associative array.

Protobuf: The payload is passed as the Message Object itself.

Custom Serializers

You can implement your own serializer by implementing RabbitEvents\Foundation\Contracts\Serializer and RabbitEvents\Foundation\Contracts\ContentType.

Register your serializer in a ServiceProvider:

New serializers are prepended to the registry, so they can override default behavior if they claim the payload.

Extensions & Ecosystem

• Redis Streams Transport - Redis Streams transport driver for RabbitEvents.
• Symfony Bundle - Official Symfony integration bundle for RabbitEvents.
• Protobuf Support - Official Google Protobuf serialization support for RabbitEvents. Required for using Protobuf messages.

Examples

Practical implementation examples and ready-to-use boilerplate classes are available in the examples directory:

• Publishers:
  • UserCreated.php - Standard publishable event with payload mapping and publishing helper.
  • TransactionalEvent.php - Transaction-safe event published only after DB commits ($afterCommit = true).
  • ContextTracingEvent.php - Distributed tracing via Laravel Context and capturing the returned message ID.
• Listeners & Subscribers:
  • AttributeListener.php - Clean attribute-based listener with #[Listener].
  • OrderEventsSubscriber.php - Handling multiple domain events within a single subscriber class.
  • IdempotentPaymentListener.php - Safe, idempotent processing and trace ID extraction.
  • WildcardListener.php - Wildcard event pattern matching and conditional propagation.
  • Listener.php - Standard listener with a custom middleware stack.
• Configuration & Providers:
  • RabbitEventsServiceProvider.php - Explicit listener mapping via the $listen array.
  • ExampleMiddleware.php - Custom event middleware implementation.

Speeding up RabbitEvents

To enhance the performance of RabbitEvents, consider installing the php-amqp extension along with the enqueue/amqp-ext package. By doing so, RabbitEvents will utilize the enqueue/amqp-ext package instead of the default enqueue/amqp-lib package. This substitution is advantageous because the C-written php-amqp package significantly outperforms the PHP-written enqueue/amqp-lib package.

You can install the php-amqp extension using the following command:

or use the way you prefer. More about it can be found here.

Next, install the enqueue/amqp-ext package with the following command:

No additional configuration is required.

Testing

We always write tests. Tests in our applications contain many mocks and fakes to test how events are published.

There is the PublishableEventTesting trait that provides assertion methods in an Event class that you want to test.

Event.php

Test.php

Don't forget to call \Mockery::close() in tearDown or similar methods of your tests.

Non-standard use

If you're using only one part of RabbitEvents, you should know a few things:

1. You remember, we're using RabbitMQ as the transport layer. In the RabbitMQ Documentation, you can find examples of how to publish your messages using a routing key. This routing key is the event name, like something.happened from the examples above.

2. RabbitEvents expects that a message body is a JSON-encoded array. Every element of an array will be passed to a Listener as a separate variable. For example:

There are 3 elements in this array, so 3 variables will be passed to a Listener (an array, a string, and an integer). If an associative array is being passed, the Dispatcher wraps this array by itself.

License

RabbitEvents is open-sourced software licensed under the MIT license.