How to 'JMS' PHP
PHPMQ gives the PHP developer JMS like abilities through the MantaRay messaging bus.
This article gives an overview of PHPMQ and its use by the PHP developer. The article assumes that the reader is familiar with both PHP and Apache, and does not describe how to install or use either product.
Definitions
MantaRay – an open source serverless messaging fabric, based on peer-to-peer technology. It is written in pure Java, supports JMS 1.1 and 1.02, and integrates with WebLogic and WebSphere. MantaRay provides guaranteed message delivery and security, and it supports transactions.
PHPMQ – an open source serverless messaging toolkit for PHP, giving the PHP developer the ability to perform JMS operations such as sending and receiving messages on queues and topics while ensuring delivery and enabling persistent messaging.
PHP / JAVA integration - PHPMQ uses the PHP / Java integration extension of PHP. More information about this extension can be found at http://php.net/manual/en/ref.java.php
PHP in the world of messaging
With PHPMQ, developers get the ability to communicate with other applications on the message bus, whether they are written in PHP, Java, or C++, using standard JMS-like messaging, by enqueuing messages to queues and dequeuing them, and by publishing messages to topics and subscribing for them.
PHPMQ runs a thin Java client that connects to the message bus and is the incoming and outgoing interface of the bus. The client uses the RMI API to communicate with a messaging interface located on the message bus. The interface exposes the messaging abilities of MantaRay and maintains a stateful session for the remote (PHP) client - this is done in order to keep the PHP client as thin as possible, and to provide a long-lived messaging session despite using a short-lived script.
Configuring MantaRay to run with PHPMQ
The MantaRay RMI API should be enabled in the configuration of MantaRay, and MantaRay should be started as a standalone before running any PHP scripts:
- Download and unzip the MantaRay messaging toolkit from http://sourceforge.net/projects/mantaray/
- Enable the RMI API by setting enable_rmi_api to true in the default_config.params configuration file.
- Enable the creation of an RMI registry by setting create_rmi_registry to true in the default_config.params configuration file, unless you are using an external RMI registry.
- Set rmi_registry_port to the port that the RMI registry will listen to, in the default_config.params configuration file.
- Set rmi_registry_host_name to the IP address or hostname of the computer where the RMI registry is located (if the registry is local, use “localhost”).
- Start MantaRay by running the org.mr.MantaStandAlone class or by running standalone.bat.
To create an instance of the PHP messaging API, a PHP script should include messaging.php like this:
include('./libraries/messaging.php');
$msg = new messaging('//localhost',10005);
$msg = new messaging('//localhost',10005);
The parameters passed at instantiation are the host name and port number of the MantaRay RMI Registry.
The PHP messaging API includes the following functions:
function enqueue($userKey, $queueName, $message)
Sends $message (string) to a queue with name $queueName (string). $userKey (string) is the
Identifier used by the messaging bus.
function dequeue($userKey, $queueName)
Returns a string message dequeued from the queue with name $queueName (string). $userKey (string) is the identifier used by the messaging bus.
function getQueues()
Returns an array of strings that are the names of queues available on the message bus.
function getTopics()
Returns an array of strings that are the names of topics available on the message bus.
function subscribe($userKey $topicName, $messagesToCash)
Adds a listener to a given $topicName (string). The listener will receive up to $messagesToCash (number) messages. $userId (string) is the identifier used by the messaging bus; use this identifier to get messages with getMessageFromTopic(....)
function getMessageFromTopic($userKey, $topicName)
Gets the messages gathered by the listener on a given $topicName (string). $userKey (string) is the identifier used by the messaging bus used when invoking subscribe(…).
function publishMessage($userKey, $topicName, $msg)
Publishes a $msg (string) to a topic with name $topicName (string). $userKey (string) is the identifier used by the messaging bus.
In the PHPMQ download package there are several examples for both queues and topics.
PHP / JAVA and Apache
Most PHP scripts run over Apache and enable a dynamic user interface with an HTTP browser.
Note that in order for the PHP / Java extension to work on Apache, you need to run the PHP as a CGI or run the PHP on a prefork compiled Apache.
RMI security note
PHPMQ uses the RMI interface of MantaRay. There are security considerations that need to be taken into account in order for the RMI API to work. Refer to: http://java.sun.com/developer/onlineTraining/rmi/. Also see the security policy at: http://patriot.net/~tvalesky/easyrmi.html