Download the PHP package medeiroz/laravel-amqp-toolkit without Composer

Package PHP/Laravel to manager, consume and publish messages with AMQP / RabbitMQ

This package was developed to facilitate the integration of Laravel applications with RabbitMQ, providing functionalities to consume and publish messages, in addition to providing a simple way to manage the AMQP / RabbitMQ infrastructure through schema migrations, inspired by Laravel's database migrations.

If you need to consume messages from RabbitMQ queues, publish messages in exchanges or queues, or manage the RabbitMQ infrastructure, this package is for you.

If you have a problems to manage the RabbitMQ Schema same as queues, exchanges and shovels, this package is for you.

Main Features

1. Schema Migrations: Use schema migrations to create, delete and manage queues, exchanges and shovels in RabbitMQ, similar to what Laravel offers for databases.
2. Consume Queue: Ability to consume messages from a RabbitMQ queue in a simple and efficient way.
3. Publish Messages: Ability to publish messages in exchanges or directly in RabbitMQ queues.

4. Event Listeners: Ability to listen to messages received from AMQP / RabbitMQ queues and exchanges, similar to Laravel's event listeners.

Requirements

• PHP >= 8.1
• Laravel >= 10

Installation

follow the steps below to install the package:

1. Install the medeiroz/laravel-amqp-toolkit package via composer
2. Publish and run migrations
3. Publish the configuration file
4. Environment variables .env
5. Configure the AMQP Queue and Laravel Listeners

1. Install the package

Run the command below to install the package via composer:

2. Publish migrations

You must publish the database migration with:

Then run the command below to create the table in the database.

3. Publish the configuration file

You can publish the configuration file with:

This is the content of the published configuration file:

4. Environment variables .env

Edit the .env file and add the environment variables of your AMQP / Rabbitmq server.

Remember to replace the values according to your environment.

5. Configure the AMQP Queue and Laravel Listeners

Edit the config/amqp-toolkit.php file and add the queues you want to consume and the listeners that will be executed when a message is received.

The key of the array is the name of the queue and the value is the listener class that will be executed when a message is received.

Example: Attach the listener PaymentReceivedListener to the queue payment-received

Refer to the configuration file for more details.

Usage

Schema Migrations

Allowed schema types are:

• queue
• exchange
• shovel

Creating a Schema

Examples

Running Migrations

Reverting Migrations

Reverting all migrations

Publishing a message to a queue or exchange

Start consuming an AMQP / RabbitMQ queue

Running the consumer for all queues

To start consuming all queues you must run the artisan command below:

To start consuming a specific queues you must run the artisan command below:

Where my-first-queue and payment-received is the name of the queues you want to consume.

Listening messages

The package provides a way to listen to messages received from AMQP / RabbitMQ queues and exchanges, similar to Laravel's event listeners.

1. Automatic listener registration

When a queue and listener are configured in the config/amqp-toolkit.php file, the listener will be automatically registered when the consumer is executed.

2. Manual listener registration

Edit the app/Providers/EventServiceProvider.php file and add the events you want to listen to.

The name of the event should be amqp.QUEUE_NAME, where QUEUE_NAME is the name of the queue you want to listen to.

app/Providers/EventServiceProvider.php

Note: The amqp:* event is a special event that listens to all messages received from all queues. The queue event is only called if the consumer is being executed

Creating a listener for the event

You can create a listener for the event you want to listen to, for this run the command below:

This package provides an event object Medeiroz\AmqpToolkit\Events\AmqpReceivedMessageEvent that contains the queue name and the message body.

If you want your events to be executed asynchronously with Laravel Horizon, you can use the ShouldQueue interface.

More about the AMQP Migration Schema

Creating an Exchange Schema

Create a new exchange schema with the command below:

Generated file:

Creating a Queue Schema

Create a new queue schema with the command below:

Generated file:

This schema creates a queue named payment-received with retry, ttl and dlq. RabbitMQ will automatically create the payment-received.retry and payment-received.dlq queues.

You can create bind the queue to an exchange by calling the bind method.

Creating a Shovel Schema

Create a new shovel schema with the command below:

Generated file:

You can create a shovel with the createShovel or createShovelIfNonExists method, passing the name of the shovel, the source and destination resources.

The source and destination are objects that represent message broker resources.

Available resources:

• Resource0dot9
  • The Message Broker resource for AMQP 0-9-1 same as RabbitMQ, Qpid, etc.
• Resource1dot0
  • The Message Broker resource for AMQP 1.0 same as Azure Service Bus, ActiveMQ, etc.

You create a shovel to move messages from Broker A to Broker B, for example.

• Move messages from RabbitMQ to Azure Service Bus
• Move messages from Azure Service Bus to RabbitMQ
• Move messages from RabbitMQ in AWS Cloud to RabbitMQ in Azure Cloud
• Move messages from Azure Service Bus to another subscription in Azure Service Bus

More about the shovel configuration can be found in the RabbitMQ Shovel documentation.

Note: The shovel schema is only available for RabbitMQ 3.8.0 or later.

All available methods in schema migration

• createQueue(string $name): Medeiroz\AmqpToolkit\SchemaMigration\Queue
  • Create a new queue
• createQueueIfNonExists(string $name): Medeiroz\AmqpToolkit\SchemaMigration\Queue
  • Create a new queue if it does not exist
• deleteQueue(string $name): void
  • Delete a queue
• deleteQueueIfExists(string $name): void
  • Delete a queue if it exists
• createExchange(string $name): Medeiroz\AmqpToolkit\SchemaMigration\Exchange
  • Create a new exchange
• createExchangeIfNonExists(string $name): Medeiroz\AmqpToolkit\SchemaMigration\Exchange
  • Create a new exchange if it does not exist
• deleteExchange(string $name): void
  • Delete an exchange
• deleteExchangeIfExists(string $name): void
  • Delete an exchange if it exists
• bind(string $queue, string $exchange, ?string $routingKey = null): Medeiroz\AmqpToolkit\SchemaMigration\Bind
  • Bind a queue to an exchange with a routing key
• bindIfExist(string $queue, string $exchange, ?string $routingKey = null): Medeiroz\AmqpToolkit\SchemaMigration\Bind
  • Bind a queue to an exchange with a routing key if the queue exists
• unbind(string $queue, string $exchange, ?string $routingKey = null): void
  • Unbind a queue from an exchange with a routing key
• unbindIfExists(string $queue, string $exchange, ?string $routingKey = null): void
  • Unbind a queue from an exchange with a routing key if the queue exists
• createShovel(string $name): Medeiroz\AmqpToolkit\SchemaMigration\Shovel
  • Create a new shovel
• createShovelIfNonExists(string $name): Medeiroz\AmqpToolkit\SchemaMigration\Shovel
  • Create a new shovel if it does not exist
• deleteShovel(string $name): void
  • Delete a shovel
• deleteShovelIfExists(string $name): void
  • Delete a shovel if it exists

More about the Shovel

The shovel is a feature that allows you to move messages between different brokers, for example, RabbitMQ to Azure Service Bus, Azure Service Bus to RabbitMQ, etc.

If your message broke is Azure Service Bus and your application as code with PHP/Laravel, you can not consume messages directly from the Azure Service Bus. You can create a shovel to move messages from Azure Service Bus to RabbitMQ and consume messages from RabbitMQ.

Forward message from Azure Service Bus to RabbitMQ

You need create a specific resources for your shovel, for example, you have the resources below:

• On Azure Service Bus
  • Subscription A (Source)
• On RabbitMQ
  • Exchange (Destination)
  • Queue A (for your PHP application to consume messages)
  • Shovel "My First Shovel"

Forward message from RabbitMQ to Azure Service Bus

You need create a specific resources for your shovel, for example, you have the resources below:

• On RabbitMQ
  • Exchange
  • Queue D (Source)
  • Shovel "My Second Shovel"
• On Azure Service Bus
  • Topic (Destination)

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Flavio Medeiros
• All Contributors

License

The MIT License (MIT). Please see License File for more information.