php-amqplib: A Pure PHP AMQP 0-9-1 Client for RabbitMQ

The gap php-amqplib fills for PHP applications on RabbitMQ

PHP has no AMQP implementation in its standard library. The AMQP 0-9-1 protocol that RabbitMQ speaks is a binary wire protocol, so a PHP process that wants to publish or consume messages needs a client that frames the protocol correctly. php-amqplib is a pure PHP implementation of that protocol, which means it installs as a Composer package with no compilation step and no C extension. The README states the library has been tested against RabbitMQ, and that it was used for the PHP examples in the official RabbitMQ tutorials and in RabbitMQ in Action.

The audience is narrow but real. You are writing a long-running PHP worker, a CLI publisher, or a service that needs full AMQP control: exchange declarations, routing keys, queue arguments, manual acknowledgements, prefetch counts. Frameworks typically wrap this library or reimplement part of it. If you want the protocol itself rather than a queue abstraction, php-amqplib is the layer you call. The package is maintained by Ramūnas Dronga, Luke Bakken and engineers working on RabbitMQ, according to the README.

How the client frames AMQP 0-9-1 in PHP

The architecture follows the protocol. A connection object such as AMQPStreamConnection opens a socket to the broker and negotiates the AMQP handshake. Channels are opened on top of that connection, and every publish, consume and queue declaration happens on a channel. Messages are AMQPMessage instances carrying a body and a properties array.

Because the protocol is implemented in PHP, every frame is encoded and decoded in userland. That is the trade-off at the centre of the library. You get portability and no extension to install; you pay for it in per-message CPU cost compared with a C extension. The README acknowledges this pressure indirectly by documenting two publishing shortcuts: batch publishing through batch_basic_publish plus publish_batch, and reusing an AMQPMessage instance so its properties do not have to be re-encoded for every message.

The repository layout reflects a mature protocol client. There is a spec/ directory, a benchmark/ directory with producer and consumer scripts, a demo/ directory with roughly two dozen runnable examples, and a docker-compose.yaml that starts RabbitMQ with the management image plus a toxiproxy service for fault injection. The Makefile exposes targets for tests, docs and benchmarks. That is the shape of a library whose correctness depends on protocol-level detail rather than on application logic.

Installing php-amqplib with Composer and publishing a first message

The README gives one install command. Run it from your project root and Composer writes the package into vendor/ alongside its dependencies.

composer require php-amqplib/php-amqplib

Then load the autoloader and import the classes you need. The README shows exactly these two imports for a stream connection and a message.

require_once __DIR__.'/vendor/autoload.php';

use PhpAmqpLib\Connection\AMQPStreamConnection;
use PhpAmqpLib\Message\AMQPMessage;

The quickest way to see the library work is the bundled demo, which needs a RabbitMQ broker reachable from your machine. Open two terminals. In the first, start the consumer; it blocks and waits for deliveries.

cd php-amqplib/demo
php amqp_consumer.php

In the second terminal, publish a message. You should see it arrive in the consumer's terminal. The README also documents a shutdown convention: publishing the literal text quit stops the consumer.

cd php-amqplib/demo
php amqp_publisher.php some text to publish
php amqp_publisher.php quit

If you prefer not to coordinate two terminals, or you want to watch the socket directly, the README points at demo/amqp_consumer_non_blocking.php. The demo directory also contains examples for publisher confirms, basic nack, basic qos, batch publishing, fanout exchanges, exclusive queues, mirrored queues, connection recovery and a signal-based heartbeat sender. Those filenames are the most reliable map of what the library supports.

Connecting to a cluster and the limits of that failover

The README documents a multiple-host connection through the static create_connection method on AMQPStreamConnection. You pass an array of host definitions, each with host, port, user, password and vhost keys, plus an options argument.

$connection = AMQPStreamConnection::create_connection([
    ['host' => HOST1, 'port' => PORT, 'user' => USER, 'password' => PASS, 'vhost' => VHOST],
    ['host' => HOST2, 'port' => PORT, 'user' => USER, 'password' => PASS, 'vhost' => VHOST]
],
$options);

The documented behaviour is sequential: the client tries HOST1 first and moves to HOST2 only if that attempt fails. The method returns the connection object for the first success, and if every attempt fails it throws the exception from the last one. Read that carefully. This is connect-time failover, not runtime failover. Nothing in the README says the client will migrate an established connection to another node after the socket dies. If your worker holds a long-lived connection and the node it landed on goes away, the recovery path is your code's responsibility. The demo file demo/connection_recovery_consume.php exists, which suggests the library exposes the pieces needed to build that recovery, but the README does not spell out the contract.

The related AMQProxy project, linked from the README, is worth understanding in this context. It is a proxy that pools and reuses connections and channels, which the README says reduces connection and channel churn and therefore CPU usage on RabbitMQ. That is an admission that opening connections and channels per request is expensive with this client.

Where php-amqplib is the wrong tool

The library gives you the AMQP protocol and almost nothing above it. There is no retry policy, no dead-letter routing logic, no serialization convention, no worker supervision. If your team wants to dispatch a job and have something else handle retries and failure, this is the wrong layer. The README itself points to enqueue/amqp-lib as an amqp interop compatible wrapper, which is the honest signal that a higher-level interface is a separate concern.

A second boundary is operational. Using php-amqplib means running and operating RabbitMQ. For applications that only need a small amount of asynchronous work, a database-backed queue removes the broker from your infrastructure entirely. Adopting this library is a commitment to a message broker, its clustering, its management interface and its upgrade cycle.

A third limit is the pure PHP implementation itself. High-throughput publishing from PHP has a per-message cost that a C extension avoids. The README's batch publishing and message reuse sections exist precisely because that cost is measurable. If your workload is millions of small messages per minute, you should benchmark the PHP path before committing to it. The repository ships a benchmark target in the Makefile that publishes 10k messages with 1KB of content and then consumes them, which is the right starting point for that measurement.

How php-amqplib differs from Symfony's AMQP messenger transport

Symfony's AMQP messenger transport is the closest thing to a drop-in alternative for application developers. The difference is the layer. Symfony's transport integrates with the Messenger component: you define a message class, dispatch it, and the framework handles serialization, routing to a transport, retry configuration and the worker command that consumes it. php-amqplib gives you none of that. You construct AMQPMessage objects, declare your own exchanges and queues, choose your own acknowledgement strategy and write your own consume loop.

That is not a defect in either project. It is a division of responsibility. If your application is already built on Symfony and your messaging needs fit the messenger model, the transport removes a large amount of boilerplate and you never touch AMQP framing. If you need behaviour the messenger abstraction does not expose, such as specific queue arguments, consumer cancel notify handling or direct control of prefetch and acknowledgements, you end up at php-amqplib anyway, because that is what sits underneath.

The same logic applies to the PHP amqp extension. The extension is a C implementation, so it avoids the userland encoding cost, but it requires installation on every host that runs your workers and it is a different API surface. php-amqplib's advantage is that Composer installs it and nothing else has to change on the machine.

Licence, maintenance and the cost of staying current

php-amqplib is released under LGPL-2.1. That is a copyleft licence with a linking exception in practice for dynamic linking, but the terms are specific and the repository's LICENSE file is the authority. If you redistribute a modified version of the library itself, the licence obligations attach to that modified library. If you merely depend on the unmodified package, the usual dynamic-linking reading applies. This is a summary of the identifier, not legal advice; have your own counsel read LICENSE before you ship a modified fork.

The repository is not archived, and the last push was on 2026-09-25. The release history shows v3.7.4 on 2025-11-23, v3.7.3 on 2025-02-18 and v3.7.2 on 2024-11-21. That is a slow, deliberate cadence rather than a fast one, which fits a protocol client: AMQP 0-9-1 does not change often. The README says server upgrades usually do not require application code changes but asks you to test before upgrading. The upgrade cost is therefore mostly on your side: pin a version in composer.json, read CHANGELOG.md between the version you run and the version you move to, and run your own consumer tests against the broker version you deploy. Because the library sits between your application and the broker, a protocol-level regression shows up as lost or duplicated messages, not as a clean exception.

Editorial conclusion

Adopt php-amqplib when your PHP process must talk to RabbitMQ directly and you accept managing connections, channels and heartbeats yourself. Skip it if you want a framework-level queue abstraction such as Symfony's AMQP messenger transport, or if you would rather not run a broker at all. Before adopting, verify the AMQP 0-9-1 semantics your topology depends on, such as publisher confirms and consumer cancel notify, and check that the demo scripts under demo/ still match the API you plan to call.

Frequently asked questions

Official sources

1. License: LGPL-2.1
2. php-amqplib/php-amqplib on GitHub
3. Project website
4. README
5. Releases