Download the PHP package goopil/rabbit-rs-native without Composer

Rabbit RS

Keep writing PHP. Let Rust handle RabbitMQ.

Rabbit RS is a native RabbitMQ runtime for PHP and Laravel workers, designed to stay alive. Your application keeps using Laravel's standard queue API; Rabbit RS handles connections, publisher confirms, recovery, and long-running consumption in a native Rust runtime.

The product is built around one feature: the long-running consumer — a worker that multiplexes many queues per broker connection, survives broker restarts and network failures, and keeps settling deliveries through recovery without manual intervention. A supervised fan-out command runs one worker per connection to span vhosts and brokers.

Delivery is at-least-once. Once a message is accepted into the confirmed delivery path, silent loss is unacceptable; duplicates are permitted and must remain measurable.

Quick start

Step 1 — Install the native extension:

Step 2 — Install the Laravel queue driver:

Step 3 — Configure the connection:

Add a rabbit-rs connection to config/queue.php (one connection = one broker = one native pool):

Configuration is connection-first — broker, credentials, routes, safety mode, and worker profile all live on the queue connection. The full reference (every key, defaults, validation, and the safety modes) is packages/laravel-queue/docs/reference.md. Optionally publish the cross-cutting defaults:

Step 4 — Publish and consume a job:

No extra configuration required: pop the queue directly — it is the connection's queue key — or declare more queues under the subscriptions escape hatch. A pop addressed to one queue of a multi-queue connection gets a dedicated single-queue consumer, so it never draws from the sibling queues (see packages/laravel-queue/docs/reference.md).

What it does

• Long-running consumer — one worker multiplexes subscriptions across many queues on its connection and survives broker restarts without manual intervention
• At-least-once delivery — publisher confirms and mandatory routing enabled by default; every publish is tracked to ACK, return, or timeout
• Deterministic recovery — connection, channels, exchanges, queues, bindings, QoS, then consumers, in a fixed order
• Weighted-fair scheduling — proportional delivery shares across subscriptions by weight
• Connection-generation-aware tokens — stale ACKs are rejected so RabbitMQ redelivers
• Bounded replay buffer — unconfirmed publications survive connection recovery in bounded memory, replayed with the same message_id
• Multi-broker fan-out — a vhost owns a distinct AMQP connection; define one connection per broker/vhost and rabbit-rs:work supervises them all
• Auto-scaling supervisor — rabbit-rs:work grows its fleet under load and releases idle workers, driven by management-API queue depth (--min-workers/--max-workers), with one-shot --once/--stop-when-empty modes for CI drains
• Octane lifecycle — flush, reload, and stop hooks prevent channel leaks
• No unsafe Rust — #![forbid(unsafe_code)] across the entire workspace

On the curated lab workloads, rabbit-rs consumes 4–6× faster than php-amqplib on the same session, with 0 losses and 0 duplicates in every reliable-mode run. Harness, methodology, and archived results: benchmarks/README.md.

Support contract

• Rust 1.96.0 (contributors only — see Contributing)

Distribution channels

Rabbit RS is distributed via three channels:

PIE selects the correct pre-compiled binary for your PHP version, architecture, operating system, libc, and thread-safety mode — including macOS Apple Silicon. Homebrew offers the same macOS binaries through the tap. Composer installs the Laravel bridge but does not install, verify, or modify system PHP: ext-rabbit_rs is a Composer suggestion and the driver fails at connection resolution until the extension is loaded (PIE installs the binary).

macOS

PIE (Apple Silicon):

Homebrew (Apple Silicon, alternative):

Requires PHP 8.4 or 8.5 (Homebrew PHP for the tap).

Manual install (Apple Silicon):

On Apple Silicon (ARM64), download the pre-compiled binary from GitHub Releases and load it manually:

Alternatively, build from source:

Intel Macs (x86_64) are not distributed as pre-compiled binaries — build from source with ./scripts/install.sh --release.

Not V1 distribution channels:

• PECL
• Debian/RPM/APK packages
• Composer plugins that install binaries
• Full PHP images bundling the extension

These are explicitly out of scope for V1. Use PIE to install the extension in your Dockerfile — see Installation.

Limitations

Read before betting a pipeline on this.

1. At-least-once means duplicates are possible — by contract, and measured. The broker redelivers any delivery that is not acknowledged (worker crash, channel loss, recovery), so consumers must treat an extra copy as normal: jobs must be idempotent. Duplicates are counted per run and become possible after any reconnect. The counters (duplicates_total, messages_redelivered) and idempotency guidance live in Reliability.
2. The replay buffer is in-process memory, not durability. Unconfirmed publications survive connection recovery in a bounded in-process buffer (1024 publications / 64 MiB by default) and are replayed with the same message_id and original deadline. A PHP process crash empties it: the broker may never have received those messages, and nothing redelivers them to you. Broker redelivery after a crash covers the consume side (duplicates, not loss) — it is not publish durability. For cross-process durability you need an external outbox, which Rabbit RS does not include (What the replay buffer is not).

Documentation

Contributing

See CONTRIBUTING.md for the full guide. Quick reference:

For architecture, build system, test strategy, and common pitfalls, see docs/development.md.

License

MIT. See LICENSE.