Applications, PHP

Web Services with NuSOAP

Doing a lot with webservices lately. Which is really a great thing if there is a central repository of information that needs to be disseminated between different external systems. I am doing a lot with NuSOAP and php SOAP. But this tutorial is going to be about the NuSOAP libraries. You can get these libraries from:
http://sourceforge.net/projects/nusoap/

First thing to do is to download this, and install into a directory that you can access. For different security reasons, it may be needed to keep these libraries outside of the accessible web directories.

The next step is to determine what needs to be required to get the data. This may include authentication and credentials, id’s, phrases, or anything else. It could be possible to not have anything required and just return all records. And that is the next step: determine what to expose. What type of information would you want to send back to the world? Hopefully it is not sensitive data, and only the data that needs to be exposed.

Now with that in mind, we are ready to go. I have set up a webservice server that has five different functions:

showPhrases – Phrases from Shakespeare plays that replace the names in the phrase with the passed in name/string
showTaxes – Calculates the tax based on the passed in price and state
showGroupItems – Shows what is needed based on a set event, all items are made up of course
showMadLib – Returns a mad lib based on passing in a number of different items
showNumbers – Returns a non associative array of numbers, requires an ID, and returns the numbers associated with that ID

Each of these functions provides a little more to view based on the webservice. The first and fourth functions will return a string of data. The second function returns an array with different data types. The third returns a complex type of a multidimensional array. I did this because there are many different tutorials out there using NuSOAP, but only seem to return a basic type and has very little to help when setting up the WSDL when it needs to be more complex. The fifth function demonstrates how to return a non associative array with the webservice in a complex type.

I will break down each function per post. But now we need a way that we can test these functions when we get them going. So the first thing to do is create a NuSOAP client to grab the exposed data. For the client, we will use the showTaxes example that has been created.

Remember, the first thing we need to do, is determine what we are going to do with code. Never just start putting down code without a plan. Always have a plan, and include requirements for the code in the plan. Our plan for the client will be as follows:

  1. Require the NuSOAP libraries
  2. Identify the WSDL we are to use
  3. Create the client with UTF-8 enabled
  4. Create a proxy
  5. Call the webservice server
  6. Grab the results
  7. Print them to the screen

This is a very basic and generic plan. When you use webservices, it is highly unlikely that you will ever just print/dump the returned data to the screen. Whatever is needed by the application for the returned data needs to be included in the plan.

So the first part, we need to create a client file wherever this will reside, so create a client.php or whatever you want to name the file. Then we need to include the NuSOAP libraries:

<?php
ini_set('display_errors',1);

require_once('nusoap/nusoap.php');

In the snippet above, I have turned on errors right now so that I can see exactly what may be going wrong. In the real world, you really do not want to do this to expose the errors. They should always be handled gracefully.

We next want to define the WSDL. The WSDL for the examples I have created is located at: http://www.hirdweb.com/webservice/index.php?wsdl. 

// Set the WSDL location
$wsdl='http://www.hirdweb.com/webservice/index.php?wsdl';

Next, we want to create the client, set the UTF-8 parameters, and do a little error trapping to make sure the client is good. 

$client = new nusoap_client($wsdl, 'wsdl');
$client->decode_utf8 = false;
$client->xml_encoding = 'UTF-8';

$err = $client->getError();
if ($err) {
    echo '<h2>Error Found While Connecting</h2><pre>' . $err . '</pre>\n';
}

This will create the client, using the WSDL (I put the WSDL in a variable for readability, but you can pass the WSDL right in the instantiation call). We are not going to decode UTF-8, but we are going to encode any XML in UTF-8. The error handler looks to see if there is an error in establishing the client. If there is one found, then it will dump that to the screen. Again, for the live world, a better error handler is needed.

Next, we set up a proxy to call the function we want, which is showTaxes. A little about this function, in case you want to explore more before the next post: This function calculates the taxes based on 9 different states in the US. They are: AZ, AL, AK, CA, OR, WA, UT, ID, WY. Any other state passed in will result in an error being spit back by the service. This webservice function needs two parameters passed to it: The price and the state. The price should be a float value, and we will get into the server more later to write in validation code to make sure it is a float. The following code would create the proxy and then make the call. (I put in a couple different examples so you can see the difference and the errors)

$proxy = $client->getProxy();

$returned_data_ca = $proxy->showTaxes("199.99", "CA");
$returned_data_or = $proxy->showTaxes("199.99", "OR");
// This will return an error
$returned_data_ny = $proxy->showTaxes("199.99", "NY");

This will make the call to the service three times for different states, and then store the returned data in the variables. Now to print them to the screen and close the file:

echo "<br /><hr /><h1>showTaxes CA Results</h1>";
echo '<pre>';
print_r($returned_data_ca);
echo '</pre>';

echo "<br /><hr /><h1>showTaxes OR Results</h1>";
echo '<pre>';
print_r($returned_data_or);
echo '</pre>';

echo "<br /><hr /><h1>showTaxes NY Results</h1>";
echo '<pre>';
print_r($returned_data_ny);
echo '</pre>';
?>

And just like that, you have a webservice client that you can now use as we get into the server.

The result has been put up at the following location:http://www.hirdweb.com/webservice/20100702.php.

Next, we will look at the creation of the NuSOAP server.