Source Article : Developer.apple.com
SOAP, the Simple Object Access Protocol, is the powerhouse of web services. It’s a highly adaptable, object-oriented protocol that exists in over 80 implementations on every popular platform, including AppleScript, JavaScript, and Cocoa. It provides a flexible communication layer between applications, regardless of platform and location. As long as they both speak SOAP, a PHP-based web application can ask a C++ database application on another continent to look up the price of a book and have the answer right away. Another Internet Developer article shows how to use SOAP with AppleScript and Perl.
SOAP was created collaboratively as an open protocol. Early in its development, XML-RPC was spun off, and now enjoys its own popularity as a simpler alternative to SOAP. Both encode messages as XML, and both use HTTP to transport those messages. SOAP, however, can use other transport protocols, offers a number of high-end features, and is developing rapidly. (For more about SOAP and web services, try XML.com’s helpful demystification.)
A SOAP transaction begins with an application making a call to a remote procedure. The SOAP client script then encodes the procedure request as an XML payload and sends it over the transport protocol to a server script. The server parses the request and passes it to a local method, which returns a response. The response is encoded as XML by the server and returned as a response to the client, which parses the response and passes the result to the original function.
There are a number of different implementations of SOAP under PHP. It’s a shifting landscape: new ones appear, and old ones aren’t maintained or simply vanish. As of this writing, the most viable PHP implementation of SOAP seems to be Dietrich Ayala’s SOAPx4, also known as NuSOAP. This implementation is the most commonly used and appears to be the most fully developed and actively maintained, and it shows every sign of continuing to be a robust and popular solution. It’s not complete—a number of features, including full documentation, are still in the works—but it’s still a highly viable and easy-to-use SOAP solution.
Installation
First, you need to get PHP up and running on your Mac. This is easy to do: check out our tutorial to get yourself set up. If you want to send SOAP messages over HTTPS, you’ll need to include the cURL module in your PHP build.
The next step is to install NuSOAP. Download the package from the developer’s site. Unzip it to get a folder of documentation, as well as the file nusoap.php, which contains the actual PHP classes that we’ll need. To use them, place nusoap.php in your PHP path and include it in the scripts you write.
The base class is nusoap_base. By using it and its subclasses, anything is possible. As an example, I’ll build a simple SOAP server script and client script, and then dissect the XML transaction they send.
A SOAP Server
Here is a simple server, written in PHP, that takes an ISBN (International Standard Book Number) as input, performs a lookup in an imaginary database, and returns the price of the corresponding book. In it, I use the soap_server class, and four methods of that class: the soap_server constructor, register, fault, and service
// function to get price from database
function lookup($ISBN) {
$query = "select price from books where isbn = ". $ISBN;
if (mysql_connect("localhost", "username", "passwd"))
else { $error = "Database connection error";
return $error; }
if (mysql_select_db("books"))
else { $error = "Database not found";
return $error; }
if ($result = mysql_query($query))
else { $error = "mysql_error()";
return $error; }
$price = mysql_result($result, 0, 0);
return $price;
}
// include the SOAP classes
require_once('nusoap.php');
// create the server object
$server = new soap_server;
// register the lookup service
$server->register('lookup');
// if the lookup fails, return an error
if $price == 0 {
$error = "Price lookup error";
}
if (isset($error)) {
$fault =
$server->fault('soap:Server','http://mydomain.com/booklookupscript.php',$err
or);
}
// send the result as a SOAP response over HTTP
$server->service($HTTP_RAW_POST_DATA);
?>
The first method I use is the soap_server constructor, which creates the server object that will be doing all the work for me. I assign that object to $server. Next is register, which tells the server what to do (in this case, to call the lookup() function). The method’s one parameter is the name of the function. There are other optional parameters that can be used to define the namespace and the SOAPAction information as specified in the SOAP specification, but those aren’t necessary for this example. The general syntax of the register method is:
register(name, in, out, namespace, SOAPAction, style)
The first parameter is the only mandatory one. in and out are arrays of input and output values; namespace and SOAPAction are used in accordance with the SOAP spec. Finally, style is used to indicate whether the data being sent is literal XML data (the default, and what I use in these examples) or RPC serialized application data.
So, the function is executed, and the returned value is passed to the server object. Then the service method returns a SOAP response to the client that initiated the request. The argument to the service method is $HTTP_RAW_POST_DATA.
Dealing with Errors
Because databases are not perfect, the script has a series of steps to catch errors. The lookup function contains three traps for different kinds of MySQL database errors. Each trap assigns an error identification string to the variable $error and returns that variable to the main function. Additionally, the main function tests the $price variable to ensure that it’s not set to zero, which would indicate a defective entry in the database.
If any one of these traps finds an error, NuSOAP’s fault method is called. This halts execution of the server script and returns the method’s parameters to the client as the string variable $fault. The syntax of the fault method is:
fault(faultcode, faultactor, faultstring, faultdetail)
The first two arguments are required, the latter two are optional. For the faultcode argument, a machine-readable fault code must be provided, as described in the SOAP spec. There are four predefined fault codes in the specification: VersionMismatch, MustUnderstand, Client, and Server. These must be given as qualified names in the namespace by prefixing them with SOAP-ENV:. A VersionMismatch error indicates incompatible namespaces. A MustUnderstand error is used when it comes across a mandatory header entry that it doesn’t understand. Client is used when the error lies in the message that was received from the client. And Server indicates a problem encountered during processing on the server, unaffiliated with the SOAP message per se. This latter code is what I used in the script when there’s a problem with the database lookup.
The faultactor argument should contain the URI where the problem originated. This is more important for transactions where numerous intermediaries are involved. In this example, I use the URI of the server script. (Note: the NuSOAP documentation implies that the faultactor element should be set to either “client” or “server.” The SOAP specification, however, says it should be a URI.)
faultstring and faultdetail are set aside for explaining the fault in human-readable language. faultstring should be a brief message indicating the nature of the problem, while faultdetail can go into more detail—it can even contain an array with specific itemized information about the fault. In my example, I pass the $error string to faultstring, and omit faultdetail.
A SOAP Client
Now I’ll write a client for an existing SOAP server, so you can see it in action. I’ll use XMethods’ Barnes & Noble Price Quote server, which acts a lot like the example server, above. It takes an ISBN as input and returns price data from Barnes & Noble.
The client script will need to send a request containing an ISBN and then parse the response. In this script, I use the soapclient class, its constructor, and call, which handles making a request and parsing the response all in one. The only method available on the server is GetPrice, which takes only one parameter, a string called isbn. It returns a floating-point variable called return.
// include the SOAP classes
require_once('nusoap.php');
// define parameter array (ISBN number)
$param = array('isbn'=>'0385503954');
// define path to server application
$serverpath ='http://services.xmethods.net:80/soap/servlet/rpcrouter';
//define method namespace
$namespace="urn:xmethods-BNPriceCheck";
// create client object
$client = new soapclient($serverpath);
// make the call
$price = $client->call('getPrice',$param,$namespace);
// if a fault occurred, output error info
if (isset($fault)) {
print "Error: ". $fault;
}
else if ($price == -1) {
print "The book is not in the database.";
} else {
// otherwise output the result
print "The price of book number ". $param[isbn] ." is $". $price;
}
// kill object
unset($client);
?>
The soapclient constructor takes a server URL as its argument. Having thus initialized the server object, I pass to the call method the name of the function I want (getPrice), the necessary parameters (the array containing the ISBN string to look up), and the required method namespace: urn:xmethods-BNPriceCheck.
The parameters for soapclient’s call method are: function name, parameter array, and three optional ones: namespace, SOAPAction, and an array of headers. The definition for the server will specify which, if any, of the optional parameters are necessary. The Barnes & Noble Price Quote server requires a method namespace definition (urn:xmethods-BNPriceCheck) but no SOAPAction or SOAP headers. Information about what this server offers and what it requires was gleaned from the server’s listing on XMethods’ index of SOAP servers. (This particular server happens to be hosted by XMethods, but the index lists a wide variety of servers, regardless of host.)
The call method of the client performs the SOAP transaction and returns the content of the server’s response to the $price variable. The script checks for the presence of $fault, which the server returns if there was an error in the transaction. If the $fault variable is set, the script outputs the error information. If there isn’t an error, it checks to see if the price returned is -1, which indicates that the requested book was not found. Otherwise, the price data is printed.
A Closer Look at the Transaction
The actual XML message sent by the client to the server looks something like this:
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
0385503954
The Envelope tag contains pointers to the global namespace definitions. It also includes pointers to the SOAP envelope schema hosted on xmlsoap.org and to the W3C’s XML schema definition. These tell the server where it’s getting definitions for the various XML tags that it’s using. The XMLSchema class (which is, as of this writing, only experimental) can be used to work with aspects of the XML schema.
The schema definition is set automatically by NuSOAP to http://www.w3.org/2001/XMLSchema. If you wish to change this, you must set the $XMLSchemaVersion global variable:
$XMLSchemaVersion = 'http://www.my.org/MYSchema/';
Detailed discussion of the ins and outs of the W3C’s XML schema can be found in O’Reilly’s new book on the subject.
Within the Envelope tag is the Body tag, which contains the body of the message. Its attributes are determined by the parameters of the function call. The name of the remote method, the method namespace, and the actual content of the message—the ISBN string—are set by the client script. NuSOAP automatically detects the variable type and incorporates the type namespace (xsd:string) in the isbn tag. If a SOAPAction had been set in the script, that would appear as a SOAPAction HTTP header.
The encoding style is set by default to http://schemas.xmlsoap.org/soap/encoding/. This is pre-set by NuSOAP as the SOAP-ENC element of the public array called namespaces. To change it, simply include a line in your script like:
$namespaces[SOAP-ENC] = 'http://my.special.encoding';
The same technique can be used to change other namespace values, if necessary. The keys of the namespaces array are SOAP-ENV, xsd, xsi, SOAP-ENC, and si, corresponding to the namespace URIs for the envelope schema, the XML schema definition (equal to $XMLSchemaVersion), the XML schema instance, the encoding style, and the SOAP interoperability test URI, respectively. The default settings for these should not need to be changed under ordinary circumstances.
The server’s XML response to the request looks like this:
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
14.65
The envelope is pretty much the same as that of the request, though you’ll notice that the server uses an older XML schema than the client. The body is also similar: the method namespace and the encoding style are the same. The ns1 package tag has Response appended to its name now: . And where the request had an element called isbn, here the core of the response is called return, and the data type is specified as float. PHP is weakly typed, so NuSOAP assigns variable types automatically.
Conclusion
NuSOAP makes working with SOAP very easy by automatically handling the complexity, although it also provides a fair amount of access to the flexibility and nuance underneath. The call method of the soapclient class and the register method of the soap_server class do a lot of work that many other SOAP implementations make you do by hand. NuSOAP offers some access to the underlayer now, and will allow more as development proceeds.
To learn more about the details of working with SOAP, refer to the SOAP specification and the API documentation that comes with NuSOAP. If you encounter a specific question about how NuSOAP handles SOAP transactions, it can be helpful to look at the nusoap.php file, which is clearly organized by class and decently commented. Going to the source, as it were, should answer most questions.
