Api

Chapter 2 - 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\wire\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\wire\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!). To discover the type of an incoming message, check the value of Method->amqpClass

\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 externalise your Amqp client configuration, and further allows you to embed broker configuration in to the client setup. This factory method creates complete \amqphp\Connection object graphs, with channels, consumers, channel event handlers and more. You can set properties and constructor arguments on any of the objects which are created. You can link to external broker configurations with xinclude (as explained in the previous section) in which case these method sequences are run during the Factory setup sequence.

The Factory follows the XML element nesting of the XML document you give it when constructing objects: to add a channels to a connection, place <channel> elements inside the <connection> element; to add consumers to a channel, place <consumer> elements inside the required <channel> element. If you want to run a sequence of methods (perhaps to initialise a queue or a binding), place <method> elements inside the <channel> either directly or via. an xinclude, as per this example. The Factory creates connections, channels, etc in the same order as they're defined in the XML file. Here's a guide to the elements that are supported, and what these mean:

• <connection> - an amqphp connection
• <channel> - an amqphp channel - must be inside a <connection>
• <consumer> - an amqphp Consumer - must be inside a <channel>
• <event_handler> - a Channel event handler - must be inside a <channel>
• <impl> - places inside elements which represent objects that will be constructed by the Factory to specify the class. For example, to create a consumer of a particular class, place a <impl>\MyConsumer</impl> inside the <consumer> element, this means the factory will use $c = new MyConsumer. Note that the Factory class sits inside a namespace, so you should use fully qualified class names throughout.
• <set_properties> - used to set properties on Factory created objects, maps child element names to object properties.
• <constr_args> - used to specify constructor parameters for objects which the factory creates.
• <confirm_mode> - flag element inside a <channel>, puts the channel in confirm mode.

As you can see in the examples linked to above, many of the elements have a k attribute, this is used by the factory as a cast hint when converting the XML to native PHP arrays, permissable hints are:

• integer, int, string, bool, boolean - native PHP casts
• const - a const value, uses the php constant function
• eval - PHP code, passed through eval

Nested XML is converted to an equivalent PHP arrays format.

Using the Factory 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 broker-common-setup.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

Previous Chapter: Amqp Concepts

Next Chapter: Sending Messages

Documentation home