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".
Once again, the RabbitEvents library helps you publish an event and handle it in another app. It doesn't make sense to use it in the same app because Laravel's Events work better for that.
Important
Attention version 7 users! A new version 7.3.0 has been released with ext-amqp support (similar to version 8.2). Update for improved performance.
- Installation via Composer
- Upgrade from 7.x to 8.x
- Publisher component
- Listener component
- Examples
- Speeding up RabbitEvents
- Non-standard use
- License
You can use Composer to install RabbitEvents into your Laravel project:
composer require nuwber/rabbitevents
After installing RabbitEvents, publish its config and a service provider using the rabbitevents:install
Artisan command:
php artisan rabbitevents:install
This command installs the config file at config/rabbitevents.php
and the Service Provider file at app/providers/RabbitEventsServiceProvider.php
.
The config file is very similar to the queue connection, but with the separate config, you'll never be confused if you have another connection to RabbitMQ.
<?php
use Enqueue\AmqpTools\RabbitMqDlxDelayStrategy;
return [
'default' => env('RABBITEVENTS_CONNECTION', 'rabbitmq'),
'connections' => [
'rabbitmq' => [
'driver' => 'rabbitmq',
'exchange' => env('RABBITEVENTS_EXCHANGE', 'events'),
'host' => env('RABBITEVENTS_HOST', 'localhost'),
'port' => env('RABBITEVENTS_PORT', 5672),
'user' => env('RABBITEVENTS_USER', 'guest'),
'pass' => env('RABBITEVENTS_PASSWORD', 'guest'),
'vhost' => env('RABBITEVENTS_VHOST', 'events'),
'delay_strategy' => env('RABBITEVENTS_DELAY_STRATEGY', RabbitMqDlxDelayStrategy::class),
'ssl' => [
'is_enabled' => env('RABBITEVENTS_SSL_ENABLED', false),
'verify_peer' => env('RABBITEVENTS_SSL_VERIFY_PEER', true),
'cafile' => env('RABBITEVENTS_SSL_CAFILE'),
'local_cert' => env('RABBITEVENTS_SSL_LOCAL_CERT'),
'local_key' => env('RABBITEVENTS_SSL_LOCAL_KEY'),
'passphrase' => env('RABBITEVENTS_SSL_PASSPHRASE', ''),
],
'read_timeout' => env('RABBITEVENTS_READ_TIMEOUT', 3.),
'write_timeout' => env('RABBITEVENTS_WRITE_TIMEOUT', 3.),
'connection_timeout' => env('RABBITEVENTS_CONNECTION_TIMEOUT', 3.),
'heartbeat' => env('RABBITEVENTS_HEARTBEAT', 0),
'persisted' => env('RABBITEVENTS_PERSISTED', false),
'lazy' => env('RABBITEVENTS_LAZY', true),
'qos' => [
'global' => env('RABBITEVENTS_QOS_GLOBAL', false),
'prefetch_size' => env('RABBITEVENTS_QOS_PREFETCH_SIZE', 0),
'prefetch_count' => env('RABBITEVENTS_QOS_PREFETCH_COUNT', 1),
]
],
],
'logging' => [
'enabled' => env('RABBITEVENTS_LOG_ENABLED', false),
'level' => env('RABBITEVENTS_LOG_LEVEL', 'info'),
'channel' => env('RABBITEVENTS_LOG_CHANNEL'),
],
];
RabbitEvents now requires PHP 8.1 or greater.
RabbitEvents now supports Laravel 9.0 or greater.
There's an issue #98 that still needs to be resolved. The default connection is always used instead.
The RabbitEvents Publisher component provides an API to publish events across the application structure. More information about how it works can be found on the RabbitEvents Publisher page.
The RabbitEvents Listener component provides an API to handle events that were published across the application structure. More information about how it works can be found on the RabbitEvents Listener page.
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:
pecl install amqp
or use the way you prefer. More about it can be found here.
Next, install the enqueue/amqp-ext
package with the following command:
composer require enqueue/amqp-ext
No additional configuration is required.
If you're using only one part of RabbitEvents, you should know a few things:
-
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. -
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:
[
{
"key": "value"
},
"string",
123
]
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.
RabbitEvents is open-sourced software licensed under the MIT license.