# php-amqp: object-oriented AMQP bindings for PHP

> php-amqp is a PHP extension that gives the AMQP C library an object-oriented face, so a PHP service can talk to any AMQP compliant broker without a separate client library. It is a low-level tool with low-level rules, notably that channel and queue objects cannot be shared between threads.

**php-amqp/php-amqp** — PHP extension to communicate with any AMQP compliant server

- Repository: https://github.com/php-amqp/php-amqp
- Website: https://pecl.php.net/package/amqp
- Stars: 584 · Forks: 121
- Language: C
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/php-amqp-php-amqp

## A C extension with a PHP object model on top

The repository describes itself as object-oriented PHP bindings for the AMQP C library, and the project description says it is a PHP extension to communicate with any AMQP compliant server. The upstream library it wraps is rabbitmq-c, and the extension is published on PECL at pecl.php.net/package/amqp, which is where the vast majority of PHP extension users will look for it first.

That framing matters for how you judge the project. This is not a wrapper around a pure PHP AMQP client, it is a binding to the same C library that other language bindings use, with a C implementation underneath. The PHP classes you work with, `AMQPConnection`, `AMQPChannel`, `AMQPQueue` and `AMQPExchange`, are the ones the extension's own documentation describes as unshareable between threads.

The primary language of the repository is C, and the source layout shows the mapping to the AMQP model: `amqp.c` and `amqp_basic_properties.c` for the core and the basic properties, `amqp_channel.c`, `amqp_connection.c`, `amqp_connection_resource.c`, `amqp_decimal.c`, `amqp_envelope.c`, `amqp_exchange.c`, `amqp_queue.c`, `amqp_timestamp.c`, `amqp_type.c` and `amqp_value.c` for the value types, plus `amqp_methods_handling.c` for the method layer. There is a `config.m4` for Unix builds and a `config.w32` for Windows, the standard pair for a PHP extension, and a `package.xml` for the PECL package definition.

The licence is one GitHub cannot classify, with a LICENSE file at the repository root, and the default branch is `latest` rather than `master`.

## Three version floors, one of them for the tests

The Requirements section is short and each line is a real constraint.

PHP must be 7.4 or newer, in either the ZTS or the non-ZTS build. Since php-amqp 2.0.0, at least version 0.8.0 of librabbitmq is required, with at least 0.10.0 recommended. And to run the tests, a RabbitMQ server of version 3.4.0 or newer is required.

The librabbitmq floor is the one to notice, because it applies from 2.0.0 onwards rather than to the whole package. A system with an old librabbitmq installed cannot simply upgrade the PHP extension and expect it to work.

The PHP floor interacts with the thread-safety question in the next section. Because the extension can be built in either the ZTS or the non-ZTS flavour, and the choice is made per platform, the same codebase can behave differently in a thread-safe SAPI and a non-thread-safe one, which is a reason to check which build your distribution ships before reading bug reports about connection handling.

## Linux: a package, the remi repo, PECL, or build it yourself

The Linux installation section opens with a practical note: some systems have the php-amqp extension available in their package repositories or available via an external repository, so it may be the preferable way to install. Fresh `php-pecl-amqp` and `librabbitmq` RPMs are available via the remi repo, which is the route for a Red Hat family system that wants a binary rather than a toolchain.

The alternative is to stay on the bleeding edge and install the extension from PECL, or to compile from sources following the PHP official docs instruction for installing a PECL extension.

The distinction in the recommendation is the usual one between a versioned package and the latest source. A distribution package gives you a repeatable build that matches the system's PHP and its librabbitmq, and it is what you want on a production host. A PECL install or a source build gives you a newer extension, and it is what you want when you need a feature the packaged version does not have, or when you are working on the extension itself.

The repository also ships a composer.json and a composer.lock, which is a little surprising in a C extension but sensible: they exist so the PHP dependencies of the test suite are managed with the usual tool.

## Windows: pick the DLL that matches your thread safety

The Windows instructions are the ones that most often go wrong, because the extension and the PHP build have to agree on thread safety.

Before downloading, the README says to check whether your PHP installation is thread safe or non-thread safe by entering the command `php -i|findstr "
  Thread"` in your terminal. Then you download the thread safe or non-thread safe version of the extension for your PHP version from the PECL package page, looking for the DLL link next to each release in the list of available releases.

After downloading, you copy the `rabbitmq.4.dll` and `rabbitmq.4.pdb` files to the PHP root folder, and you copy the `php_amqp.dll` and `php_amqp.pdb` files to the `PHP\ext` folder. Then two steps remain:

```
- Add `extension=amqp` to the `php.ini` file
- Check if the module is properly installed with <kbd>php -m</kbd>
```

The two DLLs have different jobs, and that is worth internalising. The `rabbitmq.4.dll` is the librabbitmq runtime, which is the C library the extension binds to, and the `php_amqp.dll` is the extension itself. The PDB files are debug symbols, which you copy alongside so that a crash produces a usable stack trace.

The `php -m` check at the end is the only confirmation that the extension actually loaded, and it is worth running before you spend time on a connection problem.

## Objects do not cross threads, and there is one persistent connection

The Notes and limitations section is the most useful part of the README for anyone writing production code against this extension, and it lists three rules.

First, you cannot share any of the AMQP API objects, `AMQPConnection`, `AMQPChannel`, `AMQPQueue` and `AMQPExchange`, between threads, and the instruction is to use a separate connection per thread. That is a real constraint on a PHP application whose workers are processes or threads, and it is the one most likely to surprise someone porting code from a pure PHP client.

Second, there may only be one persistent connection per connection information, which is to say per set of credentials, and an attempt to create another persistent connection with the same credentials throws an exception.

Third, channels on persistent connections are not persistent, they are destroyed between requests. So the mental model of a long-lived channel that you set up once and reuse for the life of the process is wrong for this extension.

The fourth note is a trap rather than a rule. Heartbeats are limited to blocking calls only, so if there are no operations on a connection and no active consumer set, the connection may be closed by the broker as dead. A service that publishes occasionally and does nothing in between can find its connection reaped, which looks like a mysterious disconnect rather than a heartbeat timeout.

## The test broker runs with TLS and a matrix of PHP builds

The docker-compose file in the repository root shows what the test environment looks like, and it is more than a bare broker.

The rabbitmq service runs the management image:

```yaml
services:
  rabbitmq:
    image: rabbitmq:3-management-alpine
```

and it publishes three ports, plain AMQP, TLS AMQP and the management console:

```yaml
    ports:
      # Plain TCP
      - "5672:5672/tcp"
      # SSL
      - "5671:5671/tcp"
      # Management console
      - "15672:15672/tcp"
```

Configuration is bound in read-only from the `infra` directory, the broker configuration file, the enabled plugins file and the definitions file, along with the certificates from `infra/tls/certificates`. A separate `ca` service builds from `infra/tls` and the broker depends on it completing successfully, which is how the test environment gets a certificate authority before the broker starts.

The PHP side is a matrix of build environments, with CentOS 7.4, 8.0, 8.1 and 8.2 services built from a shared definition under `infra/dev` with a `php_version` build argument, each mounting the repository and waiting for the broker. There is also a `.env` file for the environment and an `env_file` reference, and the `extra_hosts` entry maps a configurable SSL host name to 127.0.0.1 inside the containers so that certificate host names resolve locally.

In short, the test setup covers the two things that actually break in the field, TLS and multiple PHP versions.

## Stubs, an upgrade guide, and two libraries that do the same job differently

The Documentation section points in four directions, and each one answers a different question.

The official RabbitMQ tutorials are linked for the protocol itself, and the php-amqp specific examples in the rabbitmq-tutorials repository are linked for the extension's own idioms. There are stub files available that document the API of PHP AMQP, and the README says these stubs can also be used in your IDE for code completion, navigation and documentation, which is the practical way to get an IDE to understand a C extension's classes. The upgrading guide is linked to check breaking changes between versions, for example from 1.x to 2.x. And the tests are pointed at as a source of usage examples and edge cases, which is a more honest source than the tutorials when you want to know what happens on failure.

The Related libraries section names two projects that cover the same ground differently. `enqueue/amqp-ext` is an amqp interop compatible wrapper, and `symfony/amqp-messenger` provides AMQP integration for `symfony/messenger`.

That is the real alternative to this extension, and the difference in approach is worth spelling out. The extension gives you the AMQP protocol objects directly, with the performance of the C library and none of the abstraction. The alternative route gives you a queue-agnostic messaging layer where AMQP is one transport among several, so your application code is not coupled to a broker and to a threading model that requires a connection per thread.

The final part of the README is about reporting problems, and it is unusually thorough. Search the closed issues and Stack Overflow first, then submit an issue with a short definitive title, and provide platform information, the PHP interpreter version, the SAPI mode the extension is used in, the php-amqp extension version, the librabbitmq version and the make tools version. There is also a checklist of things to check before reporting, including that librabbitmq is installed and discoverable, that the extension is present and loaded, that you have correct RabbitMQ credentials, and that you are on the latest versions of everything.

## Conclusion

php-amqp fits a PHP team that needs AMQP without a pure PHP client, and that is prepared to work inside the constraints of a C extension, especially the rule that connection and channel objects cannot cross thread boundaries. It is the wrong choice for a project that wants a framework-shaped messaging abstraction, because the related libraries listed in the README do that job more directly. Verify first that your broker and librabbitmq versions meet the stated floors, that the thread-safety of your deployment matches the extension's per-thread connection rule, and whether the 2.x breaking changes in the upgrading guide affect the calls you make.

## FAQ

### What is php-amqp and what does it bind to?

It is a PHP extension that provides object-oriented PHP bindings for the AMQP C library, the rabbitmq-c project, and lets a PHP application communicate with any AMQP compliant server. The extension is published on PECL at pecl.php.net/package/amqp.

### What are the requirements for php-amqp?

PHP 7.4 or newer in either the ZTS or non-ZTS build, and since php-amqp 2.0.0 at least version 0.8.0 of librabbitmq, with 0.10.0 recommended. Running the tests additionally requires a RabbitMQ server of version 3.4.0 or newer.

### Can I share an AMQPChannel between threads in php-amqp?

No. The README states that you cannot share any of the AMQP API objects, AMQPConnection, AMQPChannel, AMQPQueue and AMQPExchange, between threads, and that you should use a separate connection per thread. It also notes there may only be one persistent connection per set of credentials.

### How do I install the php-amqp extension on Windows?

Check whether your PHP is thread safe or non-thread safe with php -i|findstr "Thread", download the matching DLL from the PECL release list, copy rabbitmq.4.dll and rabbitmq.4.pdb to the PHP root and php_amqp.dll and php_amqp.pdb to the PHP\ext folder, add extension=amqp to php.ini, and confirm with php -m.

### Why does my php-amqp connection get closed by the broker?

The README notes that heartbeats are limited to blocking calls only, so if there are no operations on a connection and no active consumer set, the connection may be closed by the broker as dead. It also notes that channels on persistent connections are not persistent and are destroyed between requests.

## Sources

- [Issues](https://github.com/php-amqp/php-amqp/issues)
- [php-amqp/php-amqp on GitHub](https://github.com/php-amqp/php-amqp)
- [Project website](https://pecl.php.net/package/amqp)
- [README](https://github.com/php-amqp/php-amqp/blob/latest/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/php-amqp-php-amqp