README

RabbitMQ queue driver for AssegaiPHP applications.

AssegaiPHP RabbitMQ Queue Integration

This package provides RabbitMQ queue support for the AssegaiPHP framework. It enables asynchronous job handling using AMQP through PhpAmqpLib.

Contribution workflow

For commit and pull request conventions in this repo, see:

• docs/commit-and-pr-guidelines.md

📦 Installation

Install via Composer:

composer require assegaiphp/rabbitmq

RabbitMQ extension requirement

This package currently requires the PHP amqp extension.

If Composer stops with an error like this:

Root composer.json requires PHP extension ext-amqp * but it is missing from your system.

the problem is usually your local PHP CLI setup, not RabbitMQ itself.

Check the PHP environment Composer is using:

php --ini
php -m | grep amqp

If amqp is missing, install or enable it for the same PHP version that runs Composer.

On Debian or Ubuntu, that is often:

sudo apt install php-amqp

or a version-specific package such as:

sudo apt install php8.5-amqp

If your distribution does not provide a package yet, pecl is often the fallback:

sudo pecl install amqp

After that, confirm the extension is loaded with php -m | grep amqp and rerun Composer.

Avoid installing with --ignore-platform-req=ext-amqp for normal development. That bypasses Composer's check, but it does not make the extension available at runtime.

⚙️ Configuration

Update your application's config/queues.php file to register the RabbitMQ driver and define your connections:

<?php

use Assegai\Rabbitmq\RabbitMQQueue;

return [
  'drivers' => [
    'rabbitmq' => RabbitMQQueue::class,
  ],
  'connections' => [
    'rabbitmq' => [
      'notifications' => [
        'host' => 'localhost',
        'port' => 5672,
        'username' => 'guest',
        'password' => 'guest',
        'vhost' => '/',
        'exchange_name' => 'notifications',
        'routing_key' => 'notifications',
        'passive' => false,
        'durable' => true,
        'exclusive' => false,
        'auto_delete' => false,
      ],
    ],
  ],
];

📝 Note:

• The drivers key maps queue driver names (like 'rabbitmq') to their fully qualified class names.
• The connections key defines queue configurations by driver and queue name (e.g., 'rabbitmq.notifications').

✨ Usage

Producing Jobs

Inject the queue connection using the #[InjectQueue] attribute:

use Assegai\Common\Interfaces\Queues\QueueInterface;
use Assegai\Core\Attributes\Injectable;
use Assegai\Core\Queues\Attributes\InjectQueue;

#[Injectable]
readonly class NotificationsService
{
  public function __construct(
    #[InjectQueue('rabbitmq.notifications')] private QueueInterface $queue
  ) {
  }

  public function send(object $payload): void
  {
    $this->queue->add($payload);
  }
}

Consuming Jobs

Define an injectable processor class for the queue:

use Assegai\Core\Attributes\Injectable;
use Assegai\Core\Queues\Attributes\QueueProcessor;

#[Injectable]
#[QueueProcessor('rabbitmq.notifications')]
final class NotificationsProcessor
{
  public function process(object $job): void
  {
    // Handle the job here.
    // For example: send an email, call another service, or write to the database.
  }
}

Register that processor in your module's provider list so the CLI can discover it.

If you want a starter file instead of writing the class from scratch, you can scaffold one with:

assegai g qp notifications --queue=rabbitmq.notifications

If you already know the job class you want to handle, you can type the generated process(...) method too:

assegai g qp notifications --queue=rabbitmq.notifications --job=Jobs/NotificationJob

If the feature already has a local Jobs folder, you can also use a bare job name:

assegai g qp notifications --queue=rabbitmq.notifications --job=notification-job

Running the Worker

Use the Assegai queue commands to discover and run processors:

assegai queue:list
assegai queue:work rabbitmq.notifications

If you want to process one job and exit, use:

assegai queue:work rabbitmq.notifications --once

If more than one processor is registered for the same queue, pass --processor to pick one explicitly.

For more information on running workers, refer to the AssegaiPHP queue guide.

🧪 Testing

You can trigger jobs via your API or CLI and observe processing output in the worker terminal.

📚 Resources

• RabbitMQ Documentation
• PhpAmqpLib GitHub
• AssegaiPHP Framework

Support

Assegai is an MIT-licensed open source project. It can grow thanks to sponsors and support by the amazing backers. If you'd like to join them, please read more here.

Stay in touch

• Author - Andrew Masiye
• Website - https://assegaiphp.com
• Twitter - @assegaiphp

License

Assegai is MIT licensed.