Api

#Amqphp API overview

This section introduces the key API components of the Amqphp library and explains their usage. Note that Amqphp is written using namespaces (the root namespace is \amqphp)

Main API classes

• \amqphp\Connection. Represents a connection to a single Amqp broker, contains the underlying TCP resource and a variable number of Amqp Channels.
• \amqphp\Channel. Represents an Amqp channel, these objects are created by calling \amqphp\Connection->openChannel() and are stored in the Connection thereafter. The Channel class uses the PHP __call method as a factory for creating Amqp messages, and has an invoke method that sends messages to the broker.
• \amqphp\Factory. A helper class which can be used to externalise broker and client configuration using XML files.
• \amqphp\Method. An object that contains a single Amqp message, whether incoming (received from broker) or outgoing (to be sent to broker).
• \amqphp\Consumer. An interface that defines operations for a consumer callback class. Objects of this interface are the end point for messages that are delivered to Amqp consumer applications.
• \amqphp\EventLoop. Implements consumer routines that listen for incoming messages. The basic behaviour is to block and wait for incoming messages indefinitely (asynchronously, using a select loop), this behaviour can be tweaked by setting an exit strategy

Basic API usage.

This section introduces the high level Amqphp components that you'll use most often.

\amqphp\Connection

Basic configuration is done by passing an assoc array to the constructor, the broker connection is established by calling connect(), and torn down by calling shutdown(). The shutdown() method closes the Amqp connection and the underlying TCP connection.

$conn = new \amqphp\Connection ($connectionParams); // object is configured
$conn->connect(); // connect to broker
// .. $conn is connected, do work, then ..
$conn->shutdown(); // You're now disconnected from the broker

\amqphp\Channel

Channels are created by calling Connection->openChannel() on a connected \amqphp\Connection object. Channels are assigned an identification number by the broker, you can get this number by calling Channel->getChanId() and you can access Channels from their containing Connection by calling Connection->getChannel($chanId) Most communication with the broker goes via. the Channel, the basic call sequence is this:

$chan = $conn->openChannel(); // Opens new Amqp channel on $conn connection
$method = $conn->queue('declare', array('queue-name' => 'my-queue'));
$response = $chan->invoke($method);

The two main uses of Channel objects are to create and send messages, the second and third lines of this example do this. The Channel class defines an __call magic method, and this acts as a factory for creating messages, the basic usage pattern this this:

$message = $conn->$class($method, array(/* assoc args */));

Allowable values for $class and $method are defined by the Amqp protocol definition and are imported in to Amqphp when you build the project using Phing (see section on the Concepts page for details of code generation).

Sometimes, the broker can send messages to a particular channel, outside the scope of a request/response pair (as outline above), for example rejected messages are returned to the sender. To handle these, you can create an instance of amqphp\ChannelEventHandler and pass this to Channel->setEventHandler(), this object will be notified when these messages arrive.

\amqphp\Method

This class represents Amqp messages, whether incoming or outgoing. To create an outgoing messages, use a Channel object as a factory (as outlined above), incoming messages are converted in to Method classes for you by Amqphp. The Amqp protocol defines a set of valid method types, each method can contain a set of parameters and a message body; the protocol also defines the name and type of the parameters and whether the method can carry content.

$method->setField($field, $value); // Set $field to $value
$method->getField($field); // Return $field
$array = $method->getFields(); // Return all field as an assoc array
$method->setContent($content); // Set message content
$content = $method->getContent(); // Get message content

When you create a method using the Channel factory, the assoc array you pass in the second argument is a shorthand way of calling setField() for each pair. If you try and set a value on an incoming message, Amqphp will raise an E_USER_WARNING error. You'll also get a warning if you try to set an invalid parameter, or if you pass an invalid parameter value. There's more documentation on Amqp methods on the RabbitMQ site (note: ignore the connection class on this page!)

\amqphp\Factory

Using this class is optional, but recommended. There are 2 basic use cases - creating Amqphp connections, channels and consumers, and invoking sequences of amqp methods, I'll address these individually:

Invoke method sequences.

See this example, part of the Amqphp demos. This file defines an exchange and a queue, and then establishes a binding between the 2. Recall that all Amqp broker configuration is done with protocol commands by client applications, this means that for complex, real world scenarios you're likely to need long lists of commands. That is the use case for this feature, to externalise this configuration, you can invoke sequences such as the example like this:

$fact = new \amqphp\Factory('my-methods.xml');
$responses = $fact->run($chan); // $chan is an open \amqphp\Channel on which all methods will be run.

Any kind of Amqp message can be sent in this way, responses are passed back to the caller in the same sequence as the methods are run

Create and configure Connection

See this example. This feature is designed to create and return Amqp connections objects, and also run methods on those connections. The example linked to above creates 2 connections, if you examine the XML data you should see that the broker connection parameters (like host name, user name, password, etc) and even nested Channels are listed. Also note the use of xinclude: this line imports the broker setup commands and runs those methods on the given channel. The example will result in the following:

• Creates 2 connections
• On each connection, opens a single channel
• On each channel, runs the broker setup sequence from an external file.

Making all this happen is pretty simple:

$fact = new \amqphp\Factory('multi-producer.xml');
$connections = $fact->getConnections();

$connections will now be an array containing 2 Connection objects, configured as described above. In fact there's a second way of doing the same thing:

$fact = new \amqphp\Factory('multi-producer.xml');
$connections = $fact->run();

This time, $connections will be an array with 4 elements, 2 Connection objects, and 2 sub-arrays containing the response Method objects for each response to the methods defined in multi-producer.xml.

The XML structure used should be pretty self-explanatory, here's a quick reference of what some of the less obvious elements mean:

• <impl> - a class name, for elements that represent objects (connections, channels..)
• <constr_args> - a set of key/value pairs to be passed as arguments to the constructor of the parent object
• <set_properties> - a set of key/value pairs of properties to set on the parent object, immediately after creating it.
• <event_handler> - specific to the Channel class, allows you to attach a ChannelEventHandler object to a newly created channel

You'll notice that many of the elements have a k attribute. This is a casting hint, and is used by the factory when converting XML to native PHP. The Factory will convert nested XML structures to equivalent nested associative arrays.

Here is a more complex example, which illustrates that you can define consumers (nested inside channels) these have an <autostart> property, which when set to true means the Factory will create a consumer and start the consume session with the Amqp broker

Generated code

As previously mentioned Amqphp requires generated code, this is created with an Xsl style sheet and the Amqp protocol definition. The only time you may need to deal with this is if you receive a message and you need to know what type it is:

$c = $method->classProto();
$m = $method->getMethodProto();
printf("You've got a %s.%s message (%d.%d)",
    $c->getSpecName(), $m->getSpecName(),
    $c->getSpecIndex(), $m->getspecIndex());

Previous Chapter: Amqp Concepts

Next Chapter: Sending Messages