Doublehops

Understanding what SOAP is and learning how to use it can be very confusing. There is much talk of SOAP on the Internet but finding an easy to understand tutorial on how to get started with it are hard to find. Therefore I have written this article for those new to SOAP.

This article assumes you have a good understanding of PHP and XML.

You use SOAP just the same way that you would any PHP class. However, in this case the class does not exist in the local applications file system, but at a remote site accessed over http.

A SOAP service is expressed as a URL. For this example I am using one I found with Google: terraservice.net/TerraService.asmx?WSDL. If we think of using a SOAP service as just another PHP class then the WSDL document is a list of all the available class methods and properties. If you open that URL in your browser you will see an XML document that lists these methods (also known as operations) and properties. If you load the page without the WSDL in the URL you will generally just get a list of the available methods: terraservice.net/TerraService.asmx. Clicking one of the operations will show the XML the service expects and the response a successful response will return. This is a typical example of how I would learn about how to use the SOAP service.

For this example I will use the GetPlaceFacts operation.This can be down by the following code:

$wsdl = 'http://terraservice.net/TerraService.asmx?WSDL';

$trace = true;
$exceptions = true;

$client = new SoapClient($wsdl, array('trace' => $trace, 'exceptions' => $exceptions));

The new object is created with the PHP5 function SoapClient(). When first testing a service it’s best to set trace and exceptions to true so that any errors can be discovered more easily. We should now have created an object of the service and are ready to send a request. For this example we will use the GetPlaceList operation. In this case we need to send data along with the request.

$xml_array['placeName'] = 'Pomona';
$xml_array['MaxItems'] = 3;
$xml_array['imagePresence'] = true;

The data here is supplied in an array rather than XML like the service expects. This is automatically converted by SoapClient.

To better understand where how to determine how these values should be entered into the array, we should check with the request format:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPlaceList xmlns="http://terraserver-usa.com/terraserver/">
      <placeName>string</placeName>
      <MaxItems>int</MaxItems>
      <imagePresence>boolean</imagePresence>
    </GetPlaceList>
  </soap:Body>
</soap:Envelope>

You can see the first element after the body element is the operation that we want to use. Following is the data that we need to send. If there were nested elements then we would need to use nested arrays to match.

Now that we have set the data we can make our request which follows:

$wsdl = 'http://terraservice.net/TerraService.asmx?WSDL';

$trace = true;
$exceptions = false;

$xml_array['placeName'] = 'Pomona';
$xml_array['MaxItems'] = 3;
$xml_array['imagePresence'] = true;

try
{
   $client = new SoapClient($wsdl, array('trace' => $trace, 'exceptions' => $exceptions));
   $response = $client->GetPlaceList($xml_array);
}

catch (Exception $e)
{
   echo "Error!";
   echo $e -> getMessage ();
   echo 'Last response: '. $client->__getLastResponse();
}

var_dump($response);

I also wrap the request in a try/catch pair to prevent any fatal errors. Also, from habit I dump the response with var_dump() so I can inspect the response in detail.

Sometimes you will find that the response values are quite nested. In this case I can trim back the response like this:

$response = $response->GetPlaceListResult->PlaceFacts;

Then we can loop through the results:

foreach($response as $key => $value)
{
   echo '<br />Place: '. $key .'<br />';
   echo 'City: '. $value->Place->City .'<br />';
   echo 'State: '. $value->Place->State .'<br />';
   echo 'Country: '. $value->Place->Country .'<br />';
}

This is a basic example of how to get started using SOAP. There is much more to it. By looking closely at the WSDL you will find which data must be supplied. This is shown by an attribute of minOccurs where equal to at least one.

For a definitive guide on SOAP I suggest going to www.w3schools.com/soap/default.asp.