README

Native ext-amqp RabbitMQ queue driver for Laravel production workloads.

Built for teams that control their infrastructure and want native RabbitMQ performance for long-running Laravel workers, connection/channel pooling, publisher confirms, quorum queues, Horizon support, Octane support, and RabbitMQ 3.13 / 4.x readiness.

Why this package?

Most Laravel RabbitMQ packages optimize for Composer-only installation. This package intentionally optimizes for production systems where the PHP runtime can include native ext-amqp.

Use it when you want:

• Laravel Queue API compatibility.
• Native ext-amqp implementation.
• Connection and channel pooling with health checks and retry backoff.
• Multi-host production configuration.
• Configurable exchanges, exchange types, and routing keys.
• Lazy queues, priority queues, quorum queues, delayed messages, dead-letter routing, and failed-message rerouting.
• Publisher confirms, transactions, RPC helpers, exchange helpers, and queue management helpers.
• Optional Laravel Horizon integration.
• Optional Laravel Octane pool reset support.
• Optional high-performance basic_consume worker mode.
• Artisan commands for declaring exchanges, declaring queues, purging queues, deleting queues, and viewing pool stats.

Documentation

• Why native ext-amqp?
• Installation guide
• Production deployment guide
• Recipes
• Benchmarks
• Support policy and compatibility matrix
• Security policy
• Contributing guide
• Upgrade guide
• Migration guide
• Comparison with vladimir-yuldashev/laravel-queue-rabbitmq

Requirements

• PHP 8.2 or higher.
• Laravel 10.x, 11.x, 12.x, or 13.x according to the Composer constraints.
• RabbitMQ 3.13 or 4.x for the primary supported/tested matrix; RabbitMQ 3.8-3.12 is best effort.
• ext-amqp PHP extension.
• ext-pcntl only when running rabbitmq:consume --num-processes with a value greater than 1.

See SUPPORT.md for the full Laravel/PHP/RabbitMQ support matrix.

Installation

composer require iamfarhad/laravel-rabbitmq

Install the AMQP extension when it is not already available:

pecl install amqp

For Debian/Ubuntu images, install the native dependency first:

sudo apt-get update
sudo apt-get install -y librabbitmq-dev libssh-dev
sudo pecl install amqp

For Docker, Alpine, Laravel Sail, and GitHub Actions examples, see the installation guide.

Publish the config:

php artisan vendor:publish \
  --provider="iamfarhad\\LaravelRabbitMQ\\LaravelRabbitQueueServiceProvider" \
  --tag="config"

Set Laravel to use RabbitMQ:

QUEUE_CONNECTION=rabbitmq

Quick start

Start RabbitMQ locally:

docker run -d --name rabbitmq \
  -p 5672:5672 \
  -p 15672:15672 \
  rabbitmq:3.13-management

Configure your application:

QUEUE_CONNECTION=rabbitmq
RABBITMQ_HOST=127.0.0.1
RABBITMQ_PORT=5672
RABBITMQ_USER=guest
RABBITMQ_PASSWORD=guest
RABBITMQ_VHOST=/
RABBITMQ_QUEUE=default

Dispatch Laravel jobs normally:

dispatch(new App\Jobs\ProcessPodcast($podcast));
dispatch(new App\Jobs\ProcessPodcast($podcast))->onQueue('podcasts');
dispatch(new App\Jobs\ProcessPodcast($podcast))->delay(now()->addMinutes(10));

Run a worker:

php artisan rabbitmq:consume --queue=default --num-processes=1

Laravel's default worker also works:

php artisan queue:work rabbitmq --queue=default

Production baseline

For production, start with explicit heartbeat, timeout, retry, and health-check settings:

QUEUE_CONNECTION=rabbitmq
RABBITMQ_CONSUME_MODE=consume
RABBITMQ_HEARTBEAT_CONNECTION=30
RABBITMQ_CONNECT_TIMEOUT=10
RABBITMQ_READ_TIMEOUT=30
RABBITMQ_WRITE_TIMEOUT=30
RABBITMQ_MAX_RETRIES=3
RABBITMQ_RETRY_DELAY=1000
RABBITMQ_HEALTH_CHECK_ENABLED=true
RABBITMQ_HEALTH_CHECK_INTERVAL=30

See production deployment for Supervisor, systemd, Docker Compose, Kubernetes, prefetch, publisher confirms, quorum queues, and dead-letter routing examples.

Configuration highlights

Multi-host configuration

'hosts' => [
    [
        'host' => 'rabbitmq-1',
        'port' => 5672,
        'user' => 'laravel',
        'password' => 'secret',
        'vhost' => '/',
    ],
    [
        'host' => 'rabbitmq-2',
        'port' => 5672,
        'user' => 'laravel',
        'password' => 'secret',
        'vhost' => '/',
    ],
],

Pool configuration

RABBITMQ_MAX_CONNECTIONS=10
RABBITMQ_MIN_CONNECTIONS=2
RABBITMQ_MAX_CHANNELS_PER_CONNECTION=100
RABBITMQ_MAX_RETRIES=3
RABBITMQ_RETRY_DELAY=1000
RABBITMQ_HEALTH_CHECK_ENABLED=true
RABBITMQ_HEALTH_CHECK_INTERVAL=30

Publishing topology

RABBITMQ_EXCHANGE=jobs
RABBITMQ_EXCHANGE_TYPE=topic
RABBITMQ_EXCHANGE_ROUTING_KEY=jobs.%s

%s is replaced with the Laravel queue name. For example, queue emails publishes with routing key jobs.emails.

Worker modes

Poll mode

poll is the default and uses basic_get. It is the safest mode and matches Laravel's worker lifecycle expectations.

php artisan rabbitmq:consume --queue=default --consume-mode=poll

Consume mode

consume uses RabbitMQ's basic_consume push-style delivery. It avoids polling overhead and is better for hot queues.

php artisan rabbitmq:consume --queue=default --consume-mode=consume

For consume mode, prefer one queue per worker process. Scale with Supervisor numprocs, containers, or Kubernetes replicas.

Common recipes

See recipes for copy-paste examples covering:

• Delayed jobs.
• Quorum queues.
• Priority queues.
• Publisher confirms.
• Dead-letter routing.
• Horizon.
• Octane.
• Multi-host failover.
• Hot queue workers.

Admin commands

# Pool stats
php artisan rabbitmq:pool-stats
php artisan rabbitmq:pool-stats --json
php artisan rabbitmq:pool-stats --watch --interval=5

# Exchanges
php artisan rabbitmq:exchange-declare jobs --type=topic

# Queues
php artisan rabbitmq:queue-declare orders --durable=1
php artisan rabbitmq:queue-declare bulk --lazy=1
php artisan rabbitmq:queue-declare quorum-orders --quorum=1
php artisan rabbitmq:queue-declare critical --priority=10
php artisan rabbitmq:queue-purge orders --force
php artisan rabbitmq:queue-delete orders --force

Testing and quality

composer format-test
composer analyse
composer test

Troubleshooting

Class AMQPConnection not found

Install and enable ext-amqp:

pecl install amqp
php -m | grep amqp

For detailed installation options, see installation guide.

Parallel worker error about pcntl

Install ext-pcntl, or run a single process:

php artisan rabbitmq:consume --queue=default --num-processes=1

Horizon events do not appear

Confirm Horizon is installed and set:

RABBITMQ_WORKER=horizon

Then restart your workers.

Support the project

If this package helps you run RabbitMQ in production with Laravel, please consider giving it a star. It helps other production teams discover the project.

Security

Please report vulnerabilities privately. See SECURITY.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md before opening a pull request.

License

The MIT License (MIT). See LICENSE for more information.