CXXXV. SAM - Simple Asynchronous Messaging

Introduction

Warning

This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk.

This extension provides access to the functionality of messaging and queueing systems, such as the IBM WebSphere MQSeries family of products, from PHP scripts. The interface is designed to make it extremely simple to do the more commonly required tasks such as deliver simple text messages to queues while still allowing skilled users to do more complex messaging operations. For many users the complexities of setting up numerous options can be simply ignored.

Installation

This should be the installation section.

API Usage

Connections

In order to perform any messaging and queueing functions a connection must be established with a messaging server by creating a SAMConnection object and calling its "connect" method, with a set of connection properties, to connect the PHP script to the messaging server. Until such time as the SAMConnection object is destroyed the connection will be maintained and available for use. All SAMConnection objects are destroyed when the PHP script exits.

A set of default properties may be used in connecting to a messaging server but as a minimum the PHP script must specify a protocol to be used.

Example 1. Creating a connection and connecting to a local Messaging Server using all defaults

<?php
   $conn
= new SAMConnection();
   
$conn->connect(SAM_WMQ);
?>

Example 2. Creating a connection and connecting to a remote Messaging Server

<?php
   $conn
= new SAMConnection();
   
$conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com,
                                 
SAM_PORT => 1506,
                                 
SAM_BROKER => mybroker));
?>

Messages

Messages sent to and received from queues are represented by the SAMMessage object. The SAMMessage object encapsulates the body of the message (if one exists) and the header properties associated with the message. A SAMMessage object is either supplied as a parameter to a messaging operation or returned as a result.

Example 3. Creating a message with a simple text body

<?php
   $msg
= new SAMMessage('This is a simple text message');
?>

Messages may have header properties associated with them that provide control over the transport of the message or further information to the receiving application. By default message properties are delivered to the underlying messaging system as strings and in this case they may be set with the following simple syntax:

Example 4. Setting a text format property using the default syntax

<?php
   $msg
->header->myPropertyName = 'textData';
?>

If it is desired to pass type information an alternative syntax may be used where the value and the type hint are passed in an associative array:

Example 5. Setting a property using a type hint

<?php
   $msg
->header->myPropertyName = (3.14159, SAM_FLOAT);
?>

Properties may also be extracted from the header of a message.

Example 6. Retrieving a property from a message header

<?php
   $myProperty
= $msg->header->myPropertyName;
?>

Messaging operations

All messaging operations are performed through calls to methods on the connection object. To add a message to a queue the "send" method is used, to obtain a message from a queue the "receive" method is used. Other methods provide publish and subscribe functionality and control of transaction boundaries.

Example 7. Adding a message to a queue and receiving a response

<?php
   $msg
= new SAMMessage('This is a simple text message');
   
$msg->header->SAM_REPLY_TO = 'queue://receive/test';
   
$correlid = $conn->send('queue://send/test', $msg);

   if (!
$correlid) {
     
// The Send failed!
     
echo "Send failed ($conn->errno) $conn->error";
   } else {
     
$resp = $conn->receive('queue://receive/test', array(SAM_SELECT => $correlid));
   }
?>

Error handling

All SAMConnection methods that provide access to messaging operations return FALSE if an error occurred in processing the request. In addition the SAMConnection object has two properties, "errno" and "error", that provide respectively the error number and text description of the last error to occur on the connection.

Example 8. Handling an error from a method that returns no result

<?php
   
if (!$conn->commit()) {
     
// The commit failed!
     
echo "Commit failed ($conn->errno) $conn->error";
   }
?>

Example 9. Handling an error from a method that returns a result

<?php
   $correlid
= $conn->send('queue://send/test', $msg);

   if (!
$correlid) {
     
// The Send failed!
     
echo "Send failed ($conn->errno) $conn->error";
   } else {
     ...
   }
?>

Predefined Classes

SAMConnection

Object representing a connection to a Messaging Server

Constructor

  • new SAMConnection - construct a new connection object to allow connection to a messaging infrastructure.

Methods

  • commit - a method that commits (successfully completes) an in-flight unit of work.

  • connect - a method that connects a PHP script to a messaging server.

  • disconnect - a method that disconnects a PHP script from a messaging server.

  • isConnected - a method that checks whether a PHP script is connected to a messaging server.

  • peek - a method that receives a message from a queue without removing it from the queue.

  • receive - a method that receives a message from a queue or subscription.

  • remove - a method that removes a message from a queue.

  • rollback - a method that cancels (rolls back) an in-flight unit of work.

  • send - a method that sends a message to a queue or posts to a topic

  • subscribe - a method that creates a subscription to one or more topics

  • unsubscribe - a method that destroys a subscription to one or more topics

Properties

  • errno - the numeric error code for the last encountered error on this connection. This property is set to 0 if the last operation was successful.

  • error - the text description for the last encountered error on this connection

SAMMessage

Object representing a message to be sent or received

Constructor

Properties

  • body - the body of the message.

  • header - the header properties of the message.

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

SAM_AUTO (string)

Automatic behaviour

SAM_BOOLEAN (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_BUS (string)

Connect attribute used to set the name of the enterprise service bus to connect to.

SAM_BYTE (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_BYTES (string)

Message body type descriptor.

SAM_DELIVERYMODE (string)

Message header property.

SAM_DOUBLE (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_ENDPOINTS (string)

Connect attribute used to define the possible endpoints to connect to.

SAM_FLOAT (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_HOST (string)

Connect attribute used to set the hostname of the required messaging server.

SAM_INT (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_LONG (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_MANUAL (string)

Manual (script controlled) behaviour

SAM_NON_PERSISTENT (string)

Connect attribute value used to request messages are not made persistent on the messaging server.

SAM_PASSWORD (string)

Connect attribute used to define the password to be used for the user account being used to connect to a messaging server that requires authorisation for connections.

SAM_PERSISTENT (string)

Connect attribute value used to request messages are made persistent on the messaging server to protect against loss of messages in the event of failure.

SAM_PORT (string)

Connect attribute used to set the port number on which to communicate with the messaging server.

SAM_PRIORITY (string)

Option name used on send requests to specify a delivery priority value.

SAM_REPLY_TO (string)

Message propery used to specify the queue identity on to which the script expects response or reply messages to be posted.

SAM_RTT (string)

Connect protocol definition for selecting the IBM Realtime Transport protocol for communication with a business integration messaging server.

SAM_SELECT (string)

Receive attribute used to set the required message selector.

SAM_STRING (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_TARGETCHAIN (string)

Connection attribute used to set the required target chain identifier.

SAM_TEXT (string)

Message body type descriptor.

SAM_TIMETOLIVE (string)

Message send option name used to specify the length of time a message should be retained in milliseconds.

SAM_TRANSACTIONS (string)

Connection attribute used to set required transactional behaviour. May be set to SAM_AUTO (default) or SAM_MANUAL.

SAM_USERID (string)

Connect attribute used to define the account to being used to connect to a messaging server that requires authorisation for connections.

SAM_WAIT (string)

Receive property used to specify the wait timeout to be used when receiving a message from a queue or subscription.

SAM_WMQ (string)

Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for communication with the desired messaging server.

SAM_WMQ_BINDINGS (string)

Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for communication with a local messaging server.

SAM_WMQ_CLIENT (string)

Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for communication with a remote messaging server.

SAM_WPM (string)

Connect protocol definition for selecting the IBM WebSphere Platform Messaging protocol for communication with a WebSphere Application Server messaging server.

Table of Contents
SAMConnection::commit() --  Commits (completes) the current unit of work.
SAMConnection::connect() --  Establishes a connection to a Messaging Server
SAMConnection::SAMConnection() --  Creates a new connection to a Messaging Server
SAMConnection::disconnect() --  Disconnects from a Messaging Server
SAMConnection->errno -- Contains the unique numeric error code of the last executed SAM operation.
SAMConnection->error -- Contains the text description of the last failed SAM operation.
SAMConnection::isConnected() --  Queries whether a connection is established to a Messaging Server
SAMConnection::peek() --  Read a message from a queue without removing it from the queue.
SAMConnection::receive() --  Receive a message from a queue or subscription.
SAMConnection::remove() --  Remove a message from a queue.
SAMConnection::rollback() --  Cancels (rolls back) an in-flight unit of work.
SAMConnection::send() --  Send a message to a queue or publish an item to a topic.
SAMConnection::subscribe() --  Create a subscription to one or more topics.
SAMConnection::unsubscribe() --  Cancel a subscription to one or more topics.
SAMMessage::body --  The body of the message.
SAMMessage::SAMMessage() --  Creates a new Message object
SAMMessage::header --  The header properties of the message.