SAM - Simple Asynchronous Messaging
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.
The SAM extension is a framework that provides a very simple API that can be used to access a number of messaging middleware systems. Currently the package includes built-in support for the MQTT (MQ Telemetry Transport) messaging protocol and support for the IBM Messaging and Queuing middleware products. SAM is designed to be readily extended to support other messaging systems and extension modules may be written in C or PHP.
The SAM framework and MQTT support can be built and used without any other prerequisites. Support for protocols other than MQTT is provided via a set of libraries and some client side code referred to as XMS.
If you only intend to use the built-in MQTT support then you can build and configure SAM as an extension or simply refer to "php_sam.php" with a "requires" or "requires_once" clause in your PHP script. In this case you need only install the code without building the extension using the pear installer:
The SAM extension interfaces to the IBM Messaging and Queuing middleware products using a set of libraries and some client side code referred to as XMS. This package is available as a free download in the guise of IBM support pack IA94. There is a description of this package and download links in the article » Introducing XMS - The IBM Message Service API.
If you intend to use SAM to access the Messaging and Queuing infrastructure within WebSphere MQ then you will also need to have installed a local MQ queue manager or installed the WebSphere MQ clients package. The clients package is freely available as a support pack (» MQC6).
If you are only aiming to experiment with sending messages to and from WebSphere Application Server queues using the WebSphere Platform Messaging protocol (WPM) then you do not need to install the MQC6 package.
After installing these packages you will need to ensure the XMS binary and, if you are using it, the MQ client bin directory are included in the PATH environment variable so that Apache and PHP can find the dependent .DLLs/libraries.
The sam extension is supplied as a PECL module, which you should be able to download and install in one step as follows:
(Depending on your php environment, you will probably need to be root to do this.)
Make sure that the module is loaded by PHP, by adding following line
If you intend to use the XMS support to access the IBM Messaging and Queuing family you must also enable the SAM XMS extension.
If you cannot use the PEAR installer, you can download the extension and build it manually:
To work with the very latest source, you'll need to extract it from cvs and build manually as above.
You will probably need to build the sam extension for Windows as there are only a limited range of pre-built binaries available from the SAM website. The extension can be built using the standard Windows extension build procedures.
You will need the PHP source tree for the version of PHP you wish to build the SAM extension against which you can obtain from php.net. This should be unpacked into a working directory of your choice.
You will also need the libraries and headers used by PHP extensions available from http://www.php.net/extra/win32build.zip and this should be unzipped so that is in your working directory.
You should have something like:
You will need a compiler such as the free version of Visual Studio C++ Express from the Microsoft web site. Also you need the Microsoft Windows Platform SDK which again can be downloaded from the Microsoft web site.
Obtain the SAM extension source using pear (pecl download sam) or by using CVS and copy the files to a new "sam" directory under the "ext" directory in your PHP source tree.
To build the extension open a build environment window by going to the start menu->all programs->microsoft platform SDK for windows-> open build environment window->windows 200 build environment-> set windows 2000 build environment (retail)
This should open a command prompt with all the environment variables set up to access the platform SDK etc. You then need to set the environment variables for Visual Studio by issuing the command "vcvars32.bat" in the window.
Change directory to your working directory e.g. cd c:\php-build. Then make sure the win32build tools are accessible by adding them to the PATH environment variable:
Run the buildconf.bat command. This should rebuild the configure.js file.
Run the cscript command with the appropriate options. To build just the SAM extension framework and MQTT support use:
To build the SAM framework and the XMS support use:
The additional parameter passed for sam_xms is the installation path to the XMS libraries and runtime that were installed as described under prerequisites at the top of this page.
You can specify whatever other cscript parameters you require to include or exclude items from the php build or select options.
Assuming all has gone well so far you can now finally run a make for the SAM framework!
Also if you are using the XMS support you must make the sam_xms extensions:
If you have used Visual Studio 2005 to build the DLLs please see below for additional steps that must be carried out before proceeding further.
The DLLs created (php_sam.dll and optionally php_sam_xms.dll) can now be copied to the
subdirectory appropriate for your PHP set-up. Make sure that the module(s) are loaded by PHP, by adding following line to
If you intend to use the XMS support to access the IBM Messgaing and Queuing family you must also enable the SAM XMS extension.
If you build the SAM extension with the Microsoft Visual Studio 2005
compiler and tools you need to perform an additional step in the build
process to ensure the
If you are using the XMS capabilities you will need to do the same with the SAM XMS DLL:
If you build the SAM extension using the compiler and libaries from Microsoft Visual Studio 2005 you will also need to ensure that the runtime components are installed on the system on which you intend to use SAM. This can be accomplished by installing Visual Studio 2005 or by using the freely distributable » runtime package.
The SAM framework can be extended to support other messaging protocols and connection mechanisms. To add support for a new protocol or connection library a support class has to be defined, either as a C extension or as a PHP script, and a "factory" script must be created. The support class must implement all the methods of the SAMConnection class though it should not inherit from SAMConnection. The factory script will be called by the SAM framework to create an instance of the implemented class. The way SAM chooses which factory to call is based on the protocol specified as the first parameter of the "connect" call.
By default the built-in MQTT support will be used if a connect call specifies a protocol of SAM_MQTT ("mqtt"), for
any other protocol SAM will attempt to use the XMS support extension. To add support for additional
protocols or to modify the default behavior entries may be added to
As can be seen from these examples the entries take the form of "sam.factory.pppp=xxx" where pppp is the protocol string specified on the connect call and xxx is a factory suffix. Note: SAM defines constants for these protocol strings such that SAM_WMQ=wmq, SAM_WPM=wpm, SAM_RTT=rtt, SAM_MQTT=mqtt, etc.
When identifying the support code to use on a connect call SAM looks up the protocol name in the
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 2095. Creating a connection and connecting to a remote WebSphere MQSeries Messaging Server
Example 2096. Creating a connection and connecting to a remote WebSphere Application Server
Example 2097. Creating a connection and connecting to an MQTT server
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 2098. Creating a message with a simple text body
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 2099. Setting a text format property using the default syntax
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 2100. Setting a property using a type hint
Properties may also be extracted from the header of a message.
Example 2101. Retrieving a property from a message header
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 2102. Adding a message to a queue and receiving a response
SAM allows messages to be sent either to queues or, for WebSphere MQ and WPM, to publish/subscribe topics. A topic desintation is specified to SAM in the usual way, i.e. in the form 'topic://fred', rather than the form 'queue://AQUEUE' used for point to point operation. To use publish/subscribe it is simply necessary to specify the correct broker name on the SAMConnect "connect" call and the desired topic in the destination argument to the SAMConnect "send" and "receive" calls. The PHP interface is otherwise identical to the point to point model.
By default, SAM creates non-durable subscriptions when using publish/subscribe. This means that if a client application is inactive when messages are published to a topic, then it will not receive them when it subsequently restarted. SAM does also allow durable subscriptions to be made to topics when using WPM or WebSphere MQ publish/subscribe. The purpose of these subscriptions is to allow data to be received by a client application even if that client was not active at the time the data was published.
Durable subscriptions are specified by using the SAMConnect "subscribe" call. This method takes the destination topic as an input parameter and returns a subscription identifier that may be used on subsequent "receive" calls. When the subscription is no longer required the SAMConnection "unsubscribe" method should be used to delete the subscription.
Example 2103. Creating a durable subscription to a topic
Example 2104. Subscribing to a topic using a WebSphere Platform Messaging (WPM) server
Example 2105. Receiving published data using a durable subscription
Example 2106. Deleting a durable subscription to a topic
All SAMConnection methods that provide access to messaging operations
Example 2107. Handling an error from a method that returns no result
Example 2108. Handling an error from a method that returns a result
Object representing a connection to a Messaging Server
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.
Table of Contents
Alternative PHP Cache
Advanced PHP debugger
Aspell functions [deprecated]
BCMath Arbitrary Precision Mathematics Functions
PHP bytecode Compiler
Bzip2 Compression Functions
CCVS API Functions [deprecated]
ClibPDF Functions [deprecated]
COM and .Net (Windows)
Character Type Functions
Cybercash Payment Functions
Credit Mutuel CyberMUT functions
Cyrus IMAP administration Functions
Date and Time Functions
Database (dbm-style) Abstraction Layer Functions
DBM Functions [deprecated]
Direct IO Functions
DOM XML Functions
Error Handling and Logging Functions
File Alteration Monitor Functions
Forms Data Format Functions
Firebird/Interbase Functions (PDO_FIREBIRD)
Function Handling Functions
Haru PDF Functions
Hyperwave API Functions
IBM Functions (PDO_IBM)
IIS Administration Functions
Imagick Image Library
Informix Functions (PDO_INFORMIX)
Ingres II Functions
IRC Gateway Functions
PHP / Java Integration
Lotus Notes Functions
MaxDB PHP Extension
Mcrypt Encryption Functions
MCVE (Monetra) Payment Functions
Ming functions for Flash
Microsoft SQL Server Functions
Microsoft SQL Server and Sybase Functions (PDO_DBLIB)
Mohawk Software Session Handler Functions
Multibyte String Functions
MySQL Functions (PDO_MYSQL)
MySQL Improved Extension
Ncurses Terminal Screen Control Functions
Object Aggregation/Composition Functions
Object property and method call overloading
ODBC Functions (Unified)
ODBC and DB2 Functions (PDO_ODBC)
OpenAL Audio Bindings
Oracle Functions [deprecated]
Oracle Functions (PDO_OCI)
Output Control Functions
Ovrimos SQL Functions
Paradox File Access
Process Control Functions
Regular Expression Functions (Perl-Compatible)
Phar archive stream and classes
Regular Expression Functions (POSIX Extended)
PostgreSQL Functions (PDO_PGSQL)
Program Execution Functions
PostScript document creation
GNU Recode Functions
RPM Header Reading Functions
SAM - Simple Asynchronous Messaging
Satellite CORBA client extension [deprecated]
SDO XML Data Access Service Functions
SDO Relational Data Access Service Functions
SESAM Database Functions
PostgreSQL Session Save Handler
Session Handling Functions
Shared Memory Functions
Standard PHP Library (SPL) Functions
SQLite Functions (PDO_SQLITE)
Secure Shell2 Functions
Shockwave Flash Functions
TCP Wrappers Functions
Variable Handling Functions
Verisign Payflow Pro Functions
XML Parser Functions
Zip File Functions
Zlib Compression Functions