RabbitExtensions

Chapter 6 - Rabbit MQ Extensions

One of the most popular Amqp brokers is RabbitMQ, the Rabbit people have added several extensions to the core Amqp 0.9.1 spec, and Amqphp implements some of these.

For the purposes of Amqphp you can break these extensions in to one of 3 types - parameter extensions, protocol extensions and API extensions.

Parameter extensions

Some extensions are implemented by passing special values in standard Method headers. Recall the standard process of sending a message:

$m = $chan->$class($meth, $args);
$chan->invoke($m);

$args is an assoc array of Amqp method parameters, these are usually scalar values, but they can also be nested assoc arrays, the nested arrays are converted in to the Amqp table data type. Tables are extensible in that the keys of the array are not fixed by the spec, so some RabbitMQ extensions are implemented by putting special values in these arrays. As an example, let's look at the alternate exchange feature, here the spec states:

When creating an exchange the name of an AE can be optionally supplied in the exchange.declare method's arguments table by specifying a key of 'alternate-exchange' and a value of type 'S' (string) containing the name.

To do this in Amqphp you need to create an \amqphp\wire\Table object and set the fields specifically:

$t = new \amqphp\wire\Table;
$t['alternate-exchange'] = new \amqphp\wire\TableField('my-ae', 'S');
$p = array(
    'exchange' => 'my-ex',
    'type' => 'direct',
    'passive' => false,
    'durable' => true,
    'auto-delete' => false,
    'internal' => false,
    'arguments' => $t);
$m = $chan->exchange('declare', $p);
$r = $chan->invoke($m);

If you browse the Amqp protocol definition, you'll see that lots of different methods use the arguments parameter to enable additional functionality, in all cases you activate the functionality as shown above. The only slight variation is that the Amqp data type may differ, as you can see in the above example, you can specify the desired data type by passing a parameter to the TableField constructor.

Protocol extensions

As has previously been mentioned, one the part of the Amqp spec is an XML document, and this is used to generate code that Amqphp uses to be able to function. Some of the RabbitMQ extensions involve adding new sections to this document, and because Amqphp uses code generation, being able to use these usually only means you have to download the new XML document and re-run the Amqphp build process (Phing). One example here is the exchange to exchange bindings, to use these you employ the "standard method sending process" (outlined above). Note that Amqphp ships with a copy of the XML spec which includes all RabbitMQ-specific extensions, so if you've downloaded a tagged copy of the library (which includes all built sources) you should able to use these features immediately.

API Extensions

Currently, Amqphp only supports one of these types of extension, publisher confirms, (more details here). To enable the publish confirms extension, you must call the \amqphp\Channel->setConfirmMode() function before sending any messages. Then, publish messages as normal, and to receive the confirms, call select() with a timeout or SELECT_COND exit strategy. If you're publishing methods from within a consume session you don't need to call select(), the existing event loop will pick up any responses. The publish confirm messages are delivered to the ChannelEventHandler class's publishConfirm() and publishNack() methods.

Note that this RabbitMQ extension also extends the protocol, so I guess you could call this a protocol extension too. The reason for the distinction is that "protocol extensions" can be used simply by regenerating the Amqphp generated code against the new XML document, you don't necessarily have to upgrade your copy of the Amqphp library to enable it. As the RabbitMQ people release more extensions, some of these will be usable by regenerating the protocol bindings, and some won't, thus you are afforded a measure of future compatibility.

Previous Chapter: Consuming messages

Next Chapter : Persistent connections

Documentation home

LocalWords: ae