BunnyPHP

Performant pure-PHP AMQP (RabbitMQ) non-blocking ReactPHP library

Requirements

BunnyPHP requires PHP 8.1 and newer.

Installation

Add as Composer dependency:

$ composer require bunny/bunny:@^0.6dev

Comparison

You might ask if there isn't a library/extension to connect to AMQP broker (e.g. RabbitMQ) already. Yes, there are multiple options:

• ext-amqp - PHP extension
• php-amqplib - pure-PHP AMQP protocol implementation

Why should you want to choose BunnyPHP instead?

• You want nice idiomatic PHP API to work with (I'm looking at you, php-amqplib). BunnyPHP interface follows PHP's common coding standards and naming conventions. See tutorial.

• You can't (don't want to) install PECL extension that has latest stable version in 2014. BunnyPHP isn't as such marked as stable yet. But it is already being used in production.

• You have both classic CLI/FPM and ReactPHP applications and need to connect to RabbitMQ. BunnyPHP comes with an asynchronous client with a synchronous API using Fibers.

Apart from that BunnyPHP is more performant than main competing library, php-amqplib. See benchmark/ directory and php-amqplib's benchmark/. (For ext-amp https://gist.github.com/WyriHaximus/65fd98e099820aded1b79e9111e02916 is used.)

Benchmarks were run as:

$ php benchmark/producer.php N & php benchmark/consumer.php

Quick Start

Producing

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$bunny = new Client($configuration);
Loop::futureTick(async(static function (): void {
  $bunny->channel()->publish(
    body:       $message,     // The message you're publishing as a string
    routingKey: 'queue_name', // Routing key, in this example the queue's name
  );
  $bunny->disconnect();
}));

// Unlike the consumer example, we're not setting signal handlers before this a very quick operation

Consuming

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$consumerCleanUp = static function () {};
$bunny = new Client($configuration);
Loop::futureTick(async(static function () use (&$consumerCleanUp): void {
    $channel = $bunny->channel();
    $response = $channel->consume(
        async(static function (Message $message, Channel $channel, Client $bunny) {
            $success = handleMessage($message); // Handle your message here
    
            if ($success) {
                $channel->ack($message); // Acknowledge message
                return;
            }
    
            $channel->nack($message); // Mark message fail, message will be redelivered
        }),
        'queue_name',
    );
    $consumerCleanUp = static fn () => $channel->cancel($response->consumerTag);
}));

// Unlike the producer example, we do need signal handlers because this process can run for weeks and we want to shut down cleanly
$signals = [SIGINT, SIGTERM, SIGHUP];
$signalHandler = async(static function () use ($signals, &$signalHandler, &$consumerCleanUp, $bunny): void {
  foreach ($signals as $signal) {
      Loop::removeSignal($signal, $signalHandler);
  }
  
  $consumerCleanUp();
  $bunny->disconnect();
}))
foreach ($signals as $signal) {
    Loop::addSignal($signal, $signalHandler);
}

Always run moving parts in a fiber

Since v0.6 Bunny has been rebuilt using Fibers. This means that every method on Client and Channel must be called inside a fiber. In the examples this will be called using a Loop::futureTick call. In your applications this might be some other trigger like a HTTP request. As long as somewhere in the direct call stack this call is inside a fiber you'll be good.

All the examples from this point on will include a Full Example on how to use that specific example using a full connection cycle inside a fiber the example. For the above that would be the following, even tho it's not doing anything:

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

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

Tutorial

Connecting

When instantiating the BunnyPHP Client accepts an array with connection options:

use Bunny\Client;
use Bunny\Configuration;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

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

use Bunny\Client;
use Bunny\Configuration;

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

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

Connecting securely using TLS(/SSL)

Options for TLS-connections should be specified as array tls:

use Bunny\Client;
use Bunny\Configuration;

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

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

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();

For options description - please see SSL context options.

Note: invalid TLS configuration will cause connection failure.

See also common configuration variants.

Providing client properties

Client Connections can present their capabilities to a server by presenting an optional client_properties table when establishing a connection.

For example, a connection name may be provided by setting the connection_name property:

use Bunny\Client;
use Bunny\Configuration;

$configuration = new Configuration(
    host:             'HOSTNAME',
    vhost:            'VHOST',    // The default vhost is '/'
    user:             'USERNAME', // The default user is 'guest'
    password:         'PASSWORD', // The default password is 'guest'
    clientProperties: [
        'connection_name' => 'My connection',
    ],
);

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

Obviously this can be dynamic, for example, on Kubernetes you can include the pod, the namespace, and any other environment variable in it:

use Bunny\Client;
use Bunny\Configuration;

$configuration = new Configuration(
    host:             'HOSTNAME',
    vhost:            'VHOST',    // The default vhost is '/'
    user:             'USERNAME', // The default user is 'guest'
    password:         'PASSWORD', // The default password is 'guest'
    clientProperties: [
        'connection_name' => 'Pod: ' . getenv('POD_NAME') . '; Release: ' . getenv('RELEASE_TAG') . '; Namespace: ' . getenv('POD_NAMESPACE'),
    ],
);

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

Publish a message

Now that we have a connection with the server we need to create a channel and declare a queue to communicate over before we can publish a message, or subscribe to a queue for that matter.

$channel = $bunny->channel();
$channel->queueDeclare('queue_name'); // Queue name

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$bunny = new Client($configuration);
Loop::futureTick(async(static function (): void {
  $bunny->connect(); // Not required as the Client::channel() method handles this for us if we don't, but added for completeness sake
  $channel = $bunny->channel();
  $channel->queueDeclare('queue_name'); // Queue name
  $channel->close(); // Not required as the Client::disconnect() method handles this for us if we don't, but added for completeness sake
  $bunny->disconnect();
}));

Publishing a message on a virtual host with quorum queues as a default

From RabbitMQ 4 queues will be standard defined as Quorum queues, those are by default durable, in order to connect to them you should use the queue declare method as follows. In the current version of RabbitMQ 3.11.15 this is already supported, if the virtual host is configured to have a default type of Quorum.

$channel = $bunny->channel();
$channel->queueDeclare('queue_name', false, true); // Queue name

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$bunny = new Client($configuration);
Loop::futureTick(async(static function (): void {
  $bunny->connect(); // Not required as the Client::channel() method handles this for us if we don't, but added for completeness sake
  $channel = $bunny->channel();
  $channel->queueDeclare('queue_name', false, true); // Queue name
  $channel->close(); // Not required as the Client::disconnect() method handles this for us if we don't, but added for completeness sake
  $bunny->disconnect();
}));

With a communication channel set up, we can now publish a message to the queue:

$channel->publish(
    $message,    // The message you're publishing as a string
    [],          // Any headers you want to add to the message
    '',          // Exchange name
    'queue_name', // Routing key, in this example the queue's name
);

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$bunny = new Client($configuration);
Loop::futureTick(async(static function (): void {
  $bunny->connect(); // Not required as the Client::channel() method handles this for us if we don't, but added for completeness sake
  $channel = $bunny->channel();
  $channel->publish(
      $message,    // The message you're publishing as a string
      [],          // Any headers you want to add to the message
      '',          // Exchange name
      'queue_name', // Routing key, in this example the queue's name
  );
  $channel->close(); // Not required as the Client::disconnect() method handles this for us if we don't, but added for completeness sake
  $bunny->disconnect();
}));

Alternatively:

$channel->publish(
    body:       $message,     // The message you're publishing as a string
    routingKey: 'queue_name', // Routing key, in this example the queue's name
);

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$bunny = new Client($configuration);
Loop::futureTick(async(static function (): void {
  $bunny->connect(); // Not required as the Client::channel() method handles this for us if we don't, but added for completeness sake
  $channel = $bunny->channel();
  $channel->publish(
      body:       $message,     // The message you're publishing as a string
      routingKey: 'queue_name', // Routing key, in this example the queue's name
  );
  $channel->close(); // Not required as the Client::disconnect() method handles this for us if we don't, but added for completeness sake
  $bunny->disconnect();
}));

Subscribing to a queue

Subscribing to a queue can be done in two ways. The first way will run indefinitely:

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

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

        $channel->nack($message); // Mark message fail, message will be redelivered
    },
    'queue_name',
);

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$consumerCleanUp = static function () {};
$bunny = new Client($configuration);
Loop::futureTick(async(static function () use (&$consumerCleanUp): void {
  $bunny->connect(); // Not required as the Client::channel() method handles this for us if we don't, but added for completeness sake
  $channel = $bunny->channel();
  $response = $channel->consume(
      async(static function (Message $message, Channel $channel, Client $bunny) {
          $success = handleMessage($message); // Handle your message here
  
          if ($success) {
              $channel->ack($message); // Acknowledge message
              return;
          }
  
          $channel->nack($message); // Mark message fail, message will be redelivered
      }),
      'queue_name',
  );
  $consumerCleanUp = static fn () => $channel->cancel($response->consumerTag);
}));

$signals = [SIGINT, SIGTERM, SIGHUP];
$signalHandler = async(static function () use ($signals, &$signalHandler, &$consumerCleanUp, $bunny): void {
  foreach ($signals as $signal) {
      Loop::removeSignal($signal, $signalHandler);
  }
  
  $consumerCleanUp();
  $bunny->disconnect();
}))
foreach ($signals as $signal) {
    Loop::addSignal($signal, $signalHandler);
}

Pop a single message from a queue

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

// Handle message

$channel->ack($message); // Acknowledge message

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$bunny = new Client($configuration);
Loop::futureTick(async(static function (): void {
  $bunny->connect(); // Not required as the Client::channel() method handles this for us if we don't, but added for completeness sake
  $channel = $bunny->channel();
  $message = $channel->get('queue_name');

  // Handle message
  
  $channel->ack($message); // Acknowledge message
  $channel->close(); // Not required as the Client::disconnect() method handles this for us if we don't, but added for completeness sake
  $bunny->disconnect();
}));

Prefetch count

A way to control how many messages are prefetched by BunnyPHP when consuming a queue is by using the channel's QOS method. In the example below only 5 messages will be prefetched. Combined with acknowledging messages this turns into an effective flow control for your applications, especially asynchronous applications. No new messages will be fetched unless one has been acknowledged.

$channel->qos(
    0, // Prefetch size
    5,  // Prefetch count
);

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

use function React\Async\async;

$configuration = new Configuration(
    host:     'HOSTNAME',
    vhost:    'VHOST',    // The default vhost is '/'
    user:     'USERNAME', // The default user is 'guest'
    password: 'PASSWORD', // The default password is 'guest'
);

$consumerCleanUp = static function () {};
$bunny = new Client($configuration);
Loop::futureTick(async(static function () use (&$consumerCleanUp): void {
  $bunny->connect(); // Not required as the Client::channel() method handles this for us if we don't, but added for completeness sake
  $channel = $bunny->channel();
  $channel->qos(
      0, // Prefetch size
      5,  // Prefetch count
  );
  $response = $channel->consume(
      static function (Message $message, Channel $channel, Client $bunny) {
          $success = handleMessage($message); // Handle your message here
  
          if ($success) {
              $channel->ack($message); // Acknowledge message
              return;
          }
  
          $channel->nack($message); // Mark message fail, message will be redelivered
      },
      'queue_name',
  );
  $consumerCleanUp = static fn () => $channel->cancel($response->consumerTag);
}));

$signals = [SIGINT, SIGTERM, SIGHUP];
$signalHandler = async(static function () use ($signals, &$signalHandler, &$consumerCleanUp, $bunny): void {
  foreach ($signals as $signal) {
      Loop::removeSignal($signal, $signalHandler);
  }
  
  $consumerCleanUp();
  $bunny->disconnect();
}))
foreach ($signals as $signal) {
    Loop::addSignal($signal, $signalHandler);
}

Asynchronous usage

Node: Up to version v0.5.x Bunny had two different clients, one sync, and one async. As of v0.6 both clients have been folder into one: An async client with a sync API.

AMQP interop

There is amqp interop compatible wrapper(s) for the bunny library.

Testing

To fully test this package, TLS certificates are required and a local RabbitMQ. On top of that a Code Style fixer and Static Analysis are used in this project. To make it as simple as possible for anyone working on this project a Makefile is in place to take care of all of that.

$ make

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

Contributing

• Large part of the PHP code (almost everything in Bunny\Protocol namespace) is generated from spec in file spec/amqp-rabbitmq-0.9.1.json. Look for DO NOT EDIT! in doc comments.

  To change generated files change spec/generate.php and run:

  $ php ./spec/generate.php
  

Broker compatibility

Works well with RabbitMQ

Does not work with ActiveMQ because it requires AMQP 1.0 which is a completely different protocol (Bunny is implementing AMQP 0.9.1)

License

BunnyPHP is licensed under MIT license. See LICENSE file.