Skip to content

Api

Jump to bottom
Robin Harvey edited this page Sep 25, 2011 · 19 revisions

#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. Amqp clients must configure the broker using Amqp methods, and this class provides a means of externalising this configuration.
  • \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.

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

Clone this wiki locally