BunnyPHP Documentation

BunnyPHP implements the AMQP 0.9.1 protocol.

• Compatible: Works well with RabbitMQ.
• Incompatible: Does not work with ActiveMQ (which requires AMQP 1.0).

Since version 0.6, BunnyPHP is built using PHP Fibers. This means that every method on Client and Channel must be called inside a fiber.

In a ReactPHP environment, this is typically achieved by wrapping the call in Loop::futureTick(async(static function() { ... })). In other applications, any trigger that ensures the direct call stack is inside a fiber will satisfy this requirement.

use Bunny\Client;
use Bunny\Configuration;
use React\EventLoop\Loop;

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',
    user:     'USERNAME',
    password: 'PASSWORD',
);

$bunny = new Client($configuration);
Loop::futureTick(async(static function (): void {
  $bunny->connect();
}));

TLS options can be passed within a DSN string using query parameters in the format tls[key]=value.

use Bunny\Client;
use Bunny\Configuration;

$configuration = Configuration::fromDSN(
    'amqp://USERNAME:PASSWORD@HOSTNAME/VHOST?tls[cafile]=ca.pem&tls[local_cert]=client.cert&tls[local_pk]=client.key',
);

$bunny = new Client($configuration);
$bunny->connect();

Use the consume method to subscribe to a queue. This runs indefinitely. Inside the callback, you should acknowledge (ack) successful messages or negatively acknowledge (nack) failed ones to trigger redelivery.

$channel->consume(
    static function (Message $message, Channel $channel, Client $bunny) {
        $success = handleMessage($message);

        if ($success) {
            $channel->ack($message);
            return;
        }

        $channel->nack($message);
    },
    'queue_name',
);

To retrieve a single message from a queue without continuous subscription, use the get method and manually acknowledge the message.

$message = $channel->get('queue_name');

// Handle message

$channel->ack($message);

You can initialize a Bunny\Configuration using an AMQP DSN string via the fromDSN method.

use Bunny\Client;
use Bunny\Configuration;

$configuration = Configuration::fromDSN('amqp://USERNAME:PASSWORD@HOSTNAME/VHOST');

$bunny = new Client($configuration);
$bunny->connect();

To publish a message, you must first obtain a channel and declare the target queue.

Note on Quorum Queues: If your virtual host is configured to use Quorum queues by default (standard in RabbitMQ 4), use queueDeclare with the durability parameter set to true: $channel->queueDeclare('queue_name', false, true);

Messages can be published using positional arguments or named arguments.

// Using positional arguments
$channel->publish(
    $message,    // string
    [],          // headers
    '',          // exchange
    'queue_name', // routing key
);

// Using named arguments (recommended)
$channel->publish(
    body:       $message,
    routingKey: 'queue_name',
);

Most code in the Bunny\Protocol namespace is automatically generated from the AMQP specification file located at spec/amqp-rabbitmq-0.9.1.json.

Warning: Do not edit these files directly; they contain DO NOT EDIT! comments. To make changes to the protocol implementation, modify spec/generate.php and run the generator script.

$ php ./spec/generate.php

If you are running tests locally and need to generate client/server TLS certificates, use the Makefile located in the test/tls directory.

$ cd test/tls && make all && cd -

To use TLS/SSL, provide a tls array in the Configuration constructor. This array accepts standard PHP SSL context options.

Common keys include:

• cafile: Path to the CA certificate.
• local_cert: Path to the client certificate.
• local_pk: Path to the client private key.

Invalid TLS configurations will cause connection failure.

use Bunny\Client;
use Bunny\Configuration;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',
    user:     'USERNAME',
    password: 'PASSWORD',
    tls:      [
        'cafile'      => 'ca.pem',
        'local_cert'  => 'client.cert',
        'local_pk'    => 'client.key',
    ],
);

$bunny = new Client($configuration);
$bunny->connect();

Add BunnyPHP as a dependency to your project using Composer. Note that the current version requirement for this specific command is ^0.6dev.

$ composer require bunny/bunny:@^0.6dev