• showNumbers – Returns an array of numbers in a non-assoc array key format
• showMadLib – Returns a mad lib based on the data it is sent. Need 4 Adjectives, 2 Adverbs, 3 Nouns, 1 Verb, and 2 Verb: Past Tense. It replies with a string that contains the madlib.
• showGroupItems – Simplistic service to return an array of items for a specific event, the ones available are: movie, picnic, drive, shopping
• showTaxes – Shows the taxes based on state taxes. Currently, the only states available in this are: AZ,AL,AK, CA, OR, WA, UT, ID, WY, Defaults to CA if no state is provided. The input for this function is an array.
• showPhrases – Shows a phrase from Shakespeare and replaces the name with the supplied name. ID is a number from 0 – 4

Although these are very basic and the real world applications are very limited, it can provide a spring board to building real world webservices that can be used for a variety of reasons. But, the power of webservices are that they can be code independent if written correctly. The server portion we have done is all in PHP. The client we have tested this on has been a PHP base. Based on the client functioning properly, we know that PHP based applications will be able to access the data. But the web is not 100% PHP based. Other code exists, which could be .NET flavors, Java, even ColdFusion. We need to ensure that the webservice built will be accepted by applications written in other languages.

This is why it is important to do cross platform/cross code clients for testing. It does not need to be a huge task or a full app. What I do is test it in the .NET C# command line. First, you will need to get some kind of Visual Studio if you do not already have it. I am not saying you have to spend thousands on Visual Studio, as they have great free IDEs available. The one I use is Visual Studio Express C# edition 2008. This is a FREE download, and can be located at
http://www.microsoft.com/express/Downloads/#2008-Visual-CS

Once that is installed you are ready to go. The first thing to do is to create a new project. I select a command line project as that will spit out data and let me know it was capable of getting the data. I created my project under the name of “HirdWebClient”, then clicked OK.

Creating the C# Project

After it creates the project, there are a couple if items to include. Click on the “Reference” folder and add the following references if they are not already there. (I may be including more than needed, and that is ok, we are not packaging this to anyone and just testing)

Adding References to the application

Add the following references:
System.Web.Services
System.ServiceModel
System.Xml
System.Collections

Make sure to add these to the top of the code as well. So the header on the “Program.cs” should look like:

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.Services;
using System.Linq;
using System.Text;
using System.ServiceModel;
using System.Xml;
using System.Collections;

Next, click the “References” folder again and select “Add Service Reference”. This will open a new window with a place to enter the WSDL address and to name the service (if you do not want the default).

Adding the Service Reference to the application

In this example, I added the WSDL address:

http://www.hirdweb.com/webservice/20100805_server.php?wsdl

After clicking “go”, I named the Namespace “hirdWeb1″. In the example, you can see that all the functions are found. So far, so good. Click “OK”. It takes me back to the Program.cs file, and now I can “Build”, “Build Solution”, or just press F6. This will save the project (if you have not already done so), and check for any errors. You should not receive any errors as there is really no code yet.

The Code should look like this to start:

namespace HirdWebClient
{
    class Program
    {
        static void Main(string[] args)
        {
        }
    }
}

In the “static void Main(string[] args)” function we will be placing all the code. In this post, I will only be checking three functions: showPhrases, showNumbers, and showTaxes. First we will start with the showPhrases. This just takes two input values, an ID and a name. But, we should declare the webservice first. In .NET, the way that the service is defined is by using a “PortTypeClient”. I renamed the webservice to erase all spaces to: HirdWebExample

$server->configureWSDL('HirdWebExample','HirdWeb Basic Webservice Example', $wsdl_addr);

So to get this webservice going and ready for use, we need to declare it as a n object and name the object, and define it as a new PortTypeClient object. Then, for ease of use, declare two variables for ID and NAME.

namespace HirdWebClient
{
    class Program
    {
        static void Main(string[] args)
        {
            hirdWeb1.HirdWebExamplePortTypeClient hw = new hirdWeb1.HirdWebExamplePortTypeClient();

            string id = "0";
            string uname = "Maurice Moss";

        }
    }
}

The good thing about the Visual Studio IDE is that helps those that may not be fluent in the language. It provides drop downs when you start typing to help guide you. Now we need to declare a result for the returning data, and call the function. Once the resultset has the data, we can print it out. Since it is a simple single string returned, it is easy to print out. And remember in C# the print statement is Console.Write or Console.WriteLine.

namespace HirdWebClient
{
    class Program
    {
        static void Main(string[] args)
        {
            hirdWeb1.HirdWebExamplePortTypeClient hw = new hirdWeb1.HirdWebExamplePortTypeClient();

            string id = "0";
            string uname = "Maurice Moss";

            hirdWeb1.showPhrases res1 = hw.showPhrases(id, uname);
            Console.WriteLine(res1.phrase);
        }
    }
}

Now rebuild the application, then click on the menu, “Debug”, then “Start Without Debugging” (or Ctrl and F5). If there are no errors during build, you should get the following to show up:

Result printout from the function showPhrases

Now we need to add in the showNumbers, and then print it out. However, since it returns an array of “strings” (which are just numbers anyway), we can not just do a Console.WriteLine. We must create a string to print these to in a foreach loop. This can be done by adding the following lines of code to the above:

hirdWeb1.showNumbers res2 = hw.showNumbers(“4″);
foreach ( string num in res2.numbers){
Console.WriteLine(num);
}

Rebuild the solution, then Start Without Debugging, and you should get the following:

Printout of the showPhrases and showNumbers functions

Whew. So now we know that the webservice is working and returning data to non-PHP applications. With one exception, the showTaxes requires an array of data. We must also ensure that the array of data is allowed to be passed in order to work. In C#, this is done a little differently.

In order to get the array to the webservice, we will not be building an array in the traditional sense, but creating an object that will add the correct data to the correct array element. First we need to instantiate the “inTaxArray” object that the webservice is going to need.

hirdWeb1.inTaxArray tax = new hirdWeb1.inTaxArray();

This is using the hirdWeb1 service reference, and creating a new “inTaxArray” object named “tax”. Now that the object is created, we need to add the correct items. This is done via the “Add” method. One element is “price” and the other is “state”. By using the Add method, we can assign those items values.

tax.price = "4.99";
tax.state = "CA";

We now have the array object ready to pass to the webservice.

hirdWeb1.showTaxes res3 = hw.showTaxes(tax);

Now that it is passed, we need to print it out, and make sure it is good. It returns an array in the “taxes” element. So we will need to reference that space when we do the print out of the data. And since the data may not be easily read as just data, we will also add some labels for the data that is being printed out.

Console.WriteLine("Original Price: " + res3.taxes.price);
Console.WriteLine("Tax on the Price: " + res3.taxes.tax);
Console.WriteLine("TOTAL AMOUNT: " + res3.taxes.total);
Console.WriteLine("Tax State: " + res3.taxes.state);

In C#, to concatenate strings, use the “+” sign, instead of the “.” sign. This will print out the each item from the returned result. And since we now have three different functions, let’s also make it look a little easier to read. So we will add some separators to the printout. The full code of the Program.cs file is below:

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.Services;
using System.Linq;
using System.Text;
using System.ServiceModel;
using System.Xml;
using System.Collections;

namespace HirdWebClient
{
    class Program
    {
        static void Main(string[] args)
        {
            hirdWeb1.HirdWebExamplePortTypeClient hw = new hirdWeb1.HirdWebExamplePortTypeClient();

            // Create variables for the showPhrases function
            string id = "0";
            string uname = "Maurice Moss";

            // Create variables for the showTaxes input array
            hirdWeb1.inTaxArray tax = new hirdWeb1.inTaxArray();
            tax.price = "4.99";
            tax.state = "CA";

            // Call each function to a resultset object
            hirdWeb1.showPhrases res1 = hw.showPhrases(id, uname);
            hirdWeb1.showNumbers res2 = hw.showNumbers("4");
            hirdWeb1.showTaxes res3 = hw.showTaxes(tax); 

            // Print out all the results
            Console.WriteLine(res1.phrase);
            Console.WriteLine("================================");
            foreach ( string num in res2.numbers){
                Console.WriteLine(num);
            }
            Console.WriteLine("================================");
            Console.WriteLine("Original Price: " + res3.taxes.price);
            Console.WriteLine("Tax on the Price: " + res3.taxes.tax);
            Console.WriteLine("TOTAL AMOUNT: " + res3.taxes.total);
            Console.WriteLine("Tax State: " + res3.taxes.state);
        }
    }
}

And that should now look like the following:

Output of all three functions

And that just about finishes up the whole NuSOAP experience. The C# command line application was able to query the PHP data and get the returned output and print it out. It now works well with PHP and C# and we have tested it in both languages. Now it is time to go out there and create and consume webservices.

We will be building on the code we used last time, so as a refresher, the code from the last post can be located at:
http://www.hirdweb.com/webservice/20100710_server.txt
http://www.hirdweb.com/webservice/20100710.txt

First off, here are the remaining functions to be exposed in the service:

• 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 webservices will require a little different structure.
showGroupItems will have a third level of complexity
showMadLib will require a long list of strings as the input
showNumbers will return an array of string elements, integer value for the element, instead of a named element

Make sure to save the file with a different name. I named it “20100720_server.php”. You will need to also update the WSDL call, otherwise it will still reference an older file name. Here is what I updated my location with:

$wsdl_addr = 'http://www.hirdweb.com/webservice/20100720_server.php';

Let’s first tackle the showGroupItems. The idea behind this is to show an example of a complex type for the returned result. We already have a complex type, but we need to make a returned result with a multidimensional array. The required input is:
id = a specific event name, in this case, we limit it to: movie, picnic, drive, shopping

For each of these events, we have a set of items that will go with it:
food – this is an array of items for food, drink and treat
equip – string containing a comma separated list of equipment needed
transport – string for the transport to/of the event
people – string of a comma separated list (or a single item) of people involved in the activity

First we need the list, so add this to the file named items.php that contains all the data for the services. We created this file in a previous post. (Just a note: in a “real world” application, these would likely be stored in a database and you would need to query the information you need in order to build the array).

$items = array(
	'movie' => array(
		'food'	=> array('food' => 'nachos with jalepenos and cheese', 'drink' => 'soda', 'treat' => 'candy'),
		'equip' => 'ticket, 3D glasses',
		'transport' => 'car',
		'people' => 'friend A, friend B, friend C',
	),
	'picnic' => array(
		'food'	=> array('food' => 'sandwiches', 'drink' => 'sports drinks', 'treat' => 'granola bars'),
		'equip' => 'basket, blanket',
		'transport' => 'van',
		'people' => 'Mom, Dad, brothers, sisters, cousins',
	),
	'drive' => array(
		'food'	=> array('food' => 'snacks', 'drink' => 'water', 'treat' => 'crackers'),
		'equip' => 'gloves, sunglasses',
		'transport' => 'sports car',
		'people' => 'myself, hot date',
	),
	'shopping' => array(
		'food'	=> array('food' => 'grapes', 'drink' => 'juice box', 'treat' => 'candybar'),
		'equip' => 'cart, list',
		'transport' => 'moving van',
	)
);

We will create a function with some very basic error checking, and be able to use our error function if there are errors.

function showGroupItems($id){
	require('items.php');
	// Make sure the id is lowercase
	$id = strtolower($id);
	if ( $id == '' ){
		return error('empty');
	}
	// make sure the item is in the array keys
	if ( !array_key_exists($id, $items) ){
		// return an error
		return error("not_found");
	}
	$final = $items[$id];

	$fin_data['status'] = array('status'=>'ok','message'=>'');
	$fin_data['group_items'] = $final;

	return $fin_data;
}

Now we need to tackle the registration of this function to the webservice. This is where we really need to think about what we need to return. First, we need to set the registration and the base complex type:

// ================================================
// === showGroupItems register
$in = array(
	'id' => 'xsd:string',
);
$out = array('return' => 'tns:showGroupItems');
$namespace = 'uri:hirdwebservice';
$soapaction = 'uri:hirdwebservice/showGroupItems';
$doc = 'Simplistic service to return an array of items for a specific event, the ones available are: movie, picnic, drive, shopping';
$server->register('showGroupItems', $in, $out, $namespace, $soapaction, 'rpc', 'encoded', $doc);
// ================================================

In this registration, we defined a “showGroupItems” type. So we need to create that to pull in the status type, and start building the showGroupItems result

// showGroupItems types ++++++++++++++++++++++++++++++++++++++++++
$server->wsdl->addComplexType('showGroupItems','complexType','struct','all','',
    array(
        'status' => array('name' => 'head', 'type' => 'tns:status_mssg'),
        'group_items' => array('name' => 'message', 'type' => 'tns:groupItems')
    )
);
// ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

In this one, we set the next level complex type to “groupItems”. In this type, we will split it into two parts. One will be for the string portions of the result, the other into the next level complex type. Add the following to the showGroupItems types code block.

$server->wsdl->addComplexType(
	'all_food','complexType','struct','all','',
	array(
		'food' => array('name' => 'food', 'type' => 'xsd:string', 'minOccurs' => "0"),
		'drink' => array('name' => 'drink', 'type' => 'xsd:string', 'minOccurs' => "0"),
		'treat' => array('name' => 'treat', 'type' => 'xsd:string', 'minOccurs' => "0"),
	)
);

$server->wsdl->addComplexType(
	'groupItems','complexType','struct','all','',
	array(
		'food' => array('name' => 'food', 'type' => 'tns:all_food'),
		'equip' => array('name' => 'equip', 'type' => 'xsd:string', 'minOccurs' => "0"),
		'transport' => array('name' => 'transport', 'type' => 'xsd:string', 'minOccurs' => "0"),
		'people' => array('name' => 'people', 'type' => 'xsd:string', 'minOccurs' => "0"),
	)
);

This definition splits the returned result. The first element item in the array is defined by a separate complex type “all_food”. The rest are regular strings. We can update all of these to be arrays as well, and that is something to try on your own. The “minOccurs” definition tells the webservice that the item is optional and may not appear. Which is ok if it does not, then the service will ignore the empty space and go on. In our data list, the last item, “shopping” does not have a ‘people’ element. So by defining the minOccurs as 0, it will not be required to print out. Now add the following to the client:

$try4 = $proxy->showGroupItems('Picnic');
$try5 = $proxy->showGroupItems('Shopping');

And print those out you should receive something similar to the following:

showGroupItems
"Picnic"
Array
(
    [status] =>
    [group_items] => Array
        (
            [food] => Array
                (
                    [food] => sandwiches
                    [drink] => sports drinks
                    [treat] => granola bars
                )

            [equip] => basket, blanket
            [transport] => van
            [people] => Mom, Dad, brothers, sisters, cousins
        )
)
"Shopping"
Array
(
    [status] =>
    [group_items] => Array
        (
            [food] => Array
                (
                    [food] => grapes
                    [drink] => juice box
                    [treat] => candybar
                )

            [equip] => cart, list
            [transport] => moving van
        )
)

Now we are completed with this function, now on to the last two. These are pretty simple. I will give you the functions, and the registration for this one, and the complexTypes definitions should be easy by now, so I will skip posting this one. Since this one is a mad lib, there is nothing to add in, we can just insert the input elements into the string.

function showMadLib($adj1, $adj2, $adj3, $adj4, $adverb1, $adverb2, $noun1, $noun2, $noun3, $verb1, $verb_past1, $verb_past2 ){
	// Put all validation code here
	if ( ($adj1 == '')||($noun1 == '')||($verb_past1 == '')||($adverb1 == '')||($adj2 == '')||($noun2 == '')||
			($noun3 == '')||($adj3 == '')||($verb1 == '')||($adverb2 == '')||($verb_past2 == '')||($adj4 == '') ){
		return error("partial");
	}

	// example submission:
	// "disagreeable","dilapidated","evanescent","ubiquitous","obediently","painfully","monkey","spaceship","boogey man","answer","photographed", "knitted"

	$mad_lib = "Today I went to the zoo. I saw a $adj1 $noun1 jumping up and down in its tree. He $verb_past1 $adverb1 through the " .
			"large tunnel that led to its $adj2 $noun2. I got some peanuts and passed them through the cage to a gigantic gray $noun3 " .
			"towering above my head. Feeding that animal made me hungry. I went to get a $adj3 scoop of ice cream. It filled my stomach." .
			"Afterwards I had to $verb1 $adverb2 to catch our bus. When I got home I $verb_past2 my mom for a $adj4 day at the zoo.";

	$fin_data['status'] = array('status'=>'ok','message'=>'');
	$fin_data['mad_lib'] = $mad_lib;

	return $fin_data;
}

The function is in place, and as you can see, it takes a lot of different input. It returns only a string as the final message, so when you build the complexType, remember that. Here is the registration:

// ================================================
// === showMadLib register
$in = array(
	'adj1' => 'xsd:string',
	'adj2' => 'xsd:string',
	'adj3' => 'xsd:string',
	'adj4' => 'xsd:string',
	'adverb1' => 'xsd:string',
	'adverb2' => 'xsd:string',
	'noun1' => 'xsd:string',
	'noun2' => 'xsd:string',
	'noun3' => 'xsd:string',
	'verb1' => 'xsd:string',
	'verb_past1' => 'xsd:string',
	'verb_past2' => 'xsd:string',
);
$out = array('return' => 'tns:showMadLib');
$namespace = 'uri:hirdwebservice';
$soapaction = 'uri:hirdwebservice/showMadLib';
$doc = 'Returns a mad lib based on the data it is sent. Need 4 Adjectives, 2 Adverbs, 3 Nouns, 1 Verb, and 2 Verb: Past Tense. It replies with a string that contains the madlib. ';
$server->register('showMadLib', $in, $out, $namespace, $soapaction, 'rpc', 'encoded', $doc);
// ================================================

Now after you build the complexType add the following to the client:

$try6 = $proxy->showMadLib("disagreeable","dilapidated","evanescent","ubiquitous","obediently","painfully","monkey","spaceship","boogey man","answer","photographed", "knitted");
$try7 = $proxy->showMadLib("hello","","","","","","",""," ","","", "");

And now you can test the function.

Lastly, we need to do a service that returns an array of data (numbers for this example) that has no associative type array. Add this to the “items.php” file:

$various = array (
	array(
		array('number' => "01"),
		array('number' => "02"),
		array('number' => "03"),
		array('number' => "04"),
		array('number' => "05"),
		array('number' => "06"),
		array('number' => "07"),
		array('number' => "08"),
		array('number' => "09"),
	),
	array(
		array('number' => "121654898"),
		array('number' => "11151"),
		array('number' => "18852"),
		array('number' => "1114885111111"),
		array('number' => "11111111111111111111"),
	),
	array(
		array('number' => "2654846354684654"),
	),
	array(
		array('number' => "303030303030303030"),
		array('number' => "32323232323232323232323232"),
	),
	array(
		array('number' => "44444444"),
		array('number' => "41414141"),
		array('number' => "42424242"),
		array('number' => "43434343"),
		array('number' => "40404040"),
	),
	array(
		array('number' => "5"),
		array('number' => "10"),
		array('number' => "15"),
		array('number' => "20"),
		array('number' => "25"),
	),
);

As you can see, it is just a regular array with numbers and nothing else. Based on the number they send to the service, it will return the string of numbers. After planning, build out the function.

function showNumbers($id){
	require("items.php");

	// place all validation code here
	if ( ($id < 0) || ($id > 5)  ){
		// return an error
		return error("custom", "numbers", "You need to enter an ID that is 0, 1, 2, 3, 4, or 5.");
	}

	$numbers = $various[$id];

	$fin_data['head'] = array('status'=>'ok','message'=>'');
	$fin_data['numbers'] = $numbers;

	return $fin_data;
}

We only want numbers from 0 to 5, so if there is anything else, then return an error. Now we need to register the function.

// ================================================
// === showNumbers register
$in = array(
	'id' => 'xsd:string',
);
$out = array('return' => 'tns:showNumbers');
$namespace = 'uri:hirdwebservice';
$soapaction = 'uri:hirdwebservice/showNumbers';
$doc = 'Returns an array of numbers in a non-assoc array key format';
$server->register('showNumbers', $in, $out, $namespace, $soapaction, 'rpc', 'encoded', $doc);
// ================================================

This is basically the same, we need an ID, and we will return a formatted complexType named “showNumbers”. But now we need to actually format those. Since we are using a non associative array for the return, we need to format a new type. This is still a complexType, but it is not a struct, but an “array”. Start with the base complexType to build off of, then add the array type which references a regular struct complexType. This is done as follows:

// showNumbers types ++++++++++++++++++++++++++++++++++++++++++
$server->wsdl->addComplexType(
	'number','complexType','struct','all','',
	array(
		'number' => array('name' => 'number', 'type' => 'xsd:string'),
	)
);

$server->wsdl->addComplexType(
	'numbers','complexType','array','',
	'SOAP-ENC:Array',
	array(),
	array(array('ref'=>'SOAP-ENC:arrayType','wsdl:arrayType'=>'tns:number[]')), 'tns:number'
);

$server->wsdl->addComplexType('showNumbers','complexType','struct','all','',
    array(
        'status' => array('name' => 'head', 'type' => 'tns:status_mssg'),
        'numbers' => array('name' => 'message', 'type' => 'tns:numbers')
    )
);
// ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The new array type will have different items we need to declare. The first being is that it is an array not a struct, we do not want all, so will do “” instead of passing “all”. Next, we need to tell the class that we want a SOAP-ENC:Array. Since we are not defining a struct, the normal position where we would put our return data is now a blank array. Finally we need to build the array type, reference in the SOAP-ENC:arrayType. Add the wsdl def to it, then make sure you add the square brackets to the named array. Now build the regular struct we already know. Add the following to the client to test the service:

$try8 = $proxy->showNumbers(2);
$try9 = $proxy->showNumbers(5);

And you should get something similar to:

showNumbers
"2"
Array
(
    [status] =>
    [numbers] => Array
        (
            [0] => Array
                (
                    [number] => 2654846354684654
                )
        )
)
"5"
Array
(
    [status] =>
    [numbers] => Array
        (
            [0] => Array
                (
                    [number] => 5
                )
            [1] => Array
                (
                    [number] => 10
                )
            [2] => Array
                (
                    [number] => 15
                )
            [3] => Array
                (
                    [number] => 20
                )
            [4] => Array
                (
                    [number] => 25
                )
        )
)

and that will complete the server side of this. These are very simplistic examples, but can be used to build on for more applicable items. For example, You may have a database full of authors and the books they wrote, along with prices, ISBN numbers, publishers, and excerpts from the book. By using a combo of the previous examples, you can create a service that allows others to query the DB based on author, that will return each book, publisher, price with tax for the state they are requesting along with an excerpt of each book.

The server for this post is located at http://www.hirdweb.com/webservice/20100720_server.php
The client for this post is located at http://www.hirdweb.com/webservice/20100720.php

Code for this post is located at:
server: http://www.hirdweb.com/webservice/20100720_server.txt
client: http://www.hirdweb.com/webservice/20100720.txt
items: http://www.hirdweb.com/webservice/items.txt

Next we will test these in ASP.NET and figure out how to really use these.

First, plan it out, always plan it out. The status message will need to accept an “error code”, a string for the struct name, and a variable for a custom message if it does fit in within the specified error codes. Now, just as a disclaimer here, this is just an example of how it can be planned. Some services may not need this extent, some may need a lot more. Remember that it needs to be able to handle the requirements of your application.

With that planned out, here is a possible solution to the function.

function error($err, $struct = 'phrase', $message = ''){
	$error['status']['status']='error';
	$error[$struct]= '';
	switch ($err) {
		case "empty":
			$error['status']['message']='There was nothing passed to the webservice, so nothing can be returned.';
			break;
		case "partial":
			$error['status']['message']="Not all required parameters were passed, so the webservice can not return any information.";
			break;
		case "not_found":
			$error['status']['message']='The parameter you passed was not found, please try again.';
			break;
		case "bounds":
			$error['status']['message']='The ID that was passed is out of the allowable boundaires. Please try your request again.';
			break;
		case "less_than_zero":
			$error['status']['message']='The number recieved is less than zero, and will not work with this service. Please double check the number and try again.';
			break;
		case 'custom':
			$error['status']['message'] = $message;
			break;
		default:
			$error['status']['message'] = 'There was a problem with your request, please try again.';
			break;
	}
	return $error;
}

In this example, I have created the basic array structure for the error, and defined a few different error codes. I am using strings for my codes, but it is possible to use integers. I am doing this mainly for readability. Each error has a specific message, and may be generic on all functions, and the best thing, this can be expanded if needed. The parameters for this function include the error code variable, setting the struct variable to use the showPhrases “phrase” structure, and setting message to null.

The codes are:
empty – used when parameters are not passed to the service
partial – when only some of the parameters are passed
not_found – the identifier was not matched to anything on the server side
bounds – the ID is outside of allowable number ranges
less_than_zero – the number is a negative number and can not be used
custom – self defined error with self defined message
default – when any of the codes do not match up, return a generic error message

After unit testing this function, and make sure the function does behave the way we need it to behave, we need to alter the function for showPhrases to allow this error functionality. The code we did before can be located at:
http://www.hirdweb.com/webservice/20100707_server.txt

We are going to modify the function for showPhrases now. Here is a possible alteration using the new error function. I added a couple more validation points as an example.

function showPhrases($id, $name){
	// Set up the phrases
	$phrases = array(
		'O NnnnnnnnnN, NnnnnnnnnN! wherefore art thou NnnnnnnnnN?',
		'But NnnnnnnnnN, If you prick us, do we not bleed? if you tickle us, do we not laugh? if you poison us, do we not die? and if you wrong us, shall we not revenge?',
		'Will all great NnnnnnnnnN\'s ocean wash this blood clean from my hand? No, this my hand will rather the multitudinous seas incarnadine, making the green one red',
		'Love looks not with the eyes, but with the mind, NnnnnnnnnN, and therefore is winged Cupid painted blind',
		'Men at some time are masters of their fates: The fault, dear NnnnnnnnnN, is not in our stars, but in ourselves, that we are underlings',
	);

	// check for empty parameters
	if ( ($name == '') || (!isset($name)) ) {
		return error("partial");
	}

	if ( $id == 100 ) {
		return error("not_found");
	}

	// place all validation code here
	if ( ($id < 0) || ($id > 4)  ){
		return error('bounds');
	}

	// Check the name for swear words
	if ( strtolower($name) == 'ass'){
		return error('custom', '', 'Please do not use drunken sailor language when using the webservice.');
	}	

	// replace all the needles with the name
	$phrase = preg_replace("/NnnnnnnnnN/", $name, $phrases[$id]);
	$fin_data['status'] = array('status'=>'ok','message'=>'');
	$fin_data['phrase'] = $phrase;

	return $fin_data;
}

In this function we have the phrases we will use, and then we start to do some validation. This is pretty basic and could probably be retooled to work a little better, but we are checking for the following:
empty parameters
id = 100 (to trigger a not found error for the example)
number range boundary violations
derogatory words (this one only including “ass”)

After it passes the checks, it does the normal process of building the response message structure. Only this time, we also need to change the status structure to:

$fin_data['status'] = array('status'=>'ok','message'=>'');

Before we can use this, though, we need to change the complexType structures in the $server object.

// Status Message Array ++++++++++++++++++++++++++++++++++++++++++
$server->wsdl->addComplexType('status_mssg','complexType','struct','all','',
    array(
    	'status' => array('name' => 'status', 'type' => 'xsd:string'),
    	'message' => array('name' => 'message', 'type' => 'xsd:string')
    )
);

// showPhrases types ++++++++++++++++++++++++++++++++++++++++++
$server->wsdl->addComplexType('showPhrases','complexType','struct','all','',
    array(
        'status' => array('name' => 'head', 'type' => 'tns:status_mssg'),
        'phrase' => array('name' => 'message', 'type' => 'xsd:string')
    )
);

We change the ‘status’ element in the showPhrases type from an xsd:string to a tns:struct-name, in this case, tns:status_mssg. The TNS name is important, because that tells the struct where to get the complex type definition. We added a new complex type. In this one, we defined two elements. Now when the response is given, it provides a multidimensional array. An example of the returned response with an error:

Array
(
    [status] => Array
        (
            [status] => error
            [message] => Not all required parameters were passed, so the webservice can not return any information.
        )

    [phrase] =>
)

You do not have to structure the status message this way, and you can keep it as a string, that is up to you. Or you can make it have even more elements, for example: the status, the message, the code to report it, url for documentation on the error, and company contact information. But by doing this, we have run through a basic complex type. If the response needs to have a multidimensional array, we know how to do this. Remember, as a good practice habit, the bottom of the WSDL is the basic, and build more complex types on top.

Now we can start on the taxes portion. I promise I will be less long winded on this one.

A function that will take a price (float type) and then calculate the tax and return it back with the original amount, tax amount and total amount with state name. I created a file, named items.php, that contains the arrays for the values of the taxes and the phrases. Here are the items for the taxes:

$tax_rates = array(
	'az'	=> '0.056',
	'al'	=> '0.04',
	'ak'	=> '0.05',
	'ca'	=> '0.0875',
	'or'	=> '0.00',
	'wa'	=> '0.065',
	'ut'	=> '0.047',
	'id'	=> '0.06',
	'wy'	=> '0.04',
);

$states = array(
	'az'	=> 'Arizona',
	'al'	=> 'Alabam',
	'ak'	=> 'Alaska',
	'ca'	=> 'California',
	'or'	=> 'Oregon',
	'wa'	=> 'Washington',
	'ut'	=> 'Utah',
	'id'	=> 'Idaho',
	'wy'	=> 'Wyoming',
);

Next we need to create the function. I am setting the default state to CA, so that if an empty string is passed, it will be set to CA automatically. Since we have already seen the error functionality in action, we can do this for brevity. I want to make sure the string is all lowercase, the price is greater than 0, and make sure that the state sent is in our array. So the following solution should be acceptable.

function showTaxes($price, $state = "ca"){
	require('items.php');

	// Make sure the state is lowercase
	$state = strtolower($state);

	// Check the array keys to validate
	$validate = array_keys($tax_rates);

	// place all validation code here
	if ( strlen($state) > 2 ){
		return error('custom', '', 'The state that was passed is not in the correct format. It should only be 2 characters');
	}

	if ( !in_array($state, $validate) ){
		// return an error
		return error("not_found");
	}

	if ( $price < 0 ){
		return error('less_than_zero');
	}

	if ( $price == '' ){
		return error('empty');
	}

	$tax = $tax_rates[$state] * $price;
	$final_price = $tax + $price;

	// set the array
	$final = array(
		'price' => $price,
		'tax'	=> money_format('%i',$tax),
		'total' => money_format('%i',$final_price),
		'state' => $states[$state],
	);

	$fin_data['status'] = array('status'=>'ok','message'=>'');
	$fin_data['taxes'] = $final;

	return  $fin_data;
}

The function validates the input, returns errors as needed. Again, I am sure there are more ways to validate, and more things to validate. If it passes all the validation, then it starts the final array formatting. In this array, there are four elements:
price
tax
total
state

So we need to create the same type of structure in our $server object.
First build the variables to register the function:

$in = array(
	'price' => 'xsd:string',
	'state' => 'xsd:string',
);
$out = array('return' => 'tns:showTaxes');
$namespace = 'uri:hirdwebservice';
$soapaction = 'uri:hirdwebservice/showTaxes';
$doc = 'Shows the taxes based on state taxes. Currently, the only states available in this are: AZ,AL,AK, CA, OR, WA, UT, ID, WY, Defaults to CA if no state is provided.';
$server->register('showTaxes', $in, $out, $namespace, $soapaction, 'rpc', 'encoded', $doc);

Now we need to build the structures. This will require 3 structures: the base complex type that splits the status and response, and the status structure, and the response structure. Since we already have the status structure in place, we need to worry about the response structure.

$server->wsdl->addComplexType('taxes','complexType','struct','all','',
	array(
		'price' => array('name' => 'price', 'type' => 'xsd:float', 'minOccurs' => "0"),
		'tax' => array('name' => 'tax', 'type' => 'xsd:float', 'minOccurs' => "0"),
		'total' => array('name' => 'total', 'type' => 'xsd:float', 'minOccurs' => "0"),
		'state' => array('name' => 'state', 'type' => 'xsd:string', 'minOccurs' => "0"),
	)
);

$server->wsdl->addComplexType('showTaxes','complexType','struct','all','',
    array(
        'status' => array('name' => 'head', 'type' => 'tns:status_mssg'),
        'taxes' => array('name' => 'message', 'type' => 'tns:taxes')
    )
);

The base structure defines the status structure and sets the type the tns:status_mssg. The response sets the name to “taxes” and the type to tns:taxes. Now the name of the TNS structure can be whatever you really want to call it, but it must be the same as the complex type that is defined. For example, you can not call a complex type of “type1forme” and have the actual complex type added as ‘type_for_me’. I made this bold in the example above so you can see the connection between the two. The taxes structure has four elements, just like the function returns. When the response is given, it will show up as:

Array
(
    [status] => Array
        (
            [status] => ok
            [message] =>
        )

    [taxes] => Array
        (
            [price] => 12.18
            [tax] => 0.68
            [total] => 12.86
            [state] => Arizona
        )

)

I created a test client for this entry, and this is located at:
http://www.hirdweb.com/webservice/20100710.php

It shows the response for the examples with showPhrases (1 good call, 1 error), and showTaxes (2 good calls, 2 errors).

The next post will include the rest of the functions, with one of them adding a third level of complexity to the response, and completing the server.

The code for the server portion of this post: http://www.hirdweb.com/webservice/20100710_server.txt

The code for the client side of this post: http://www.hirdweb.com/webservice/20100710.txt

Using the previous information in the post, we have a client that we can text the service on. Before I complete the webservice server, I always do some quick testing of the functionality before sending it to the web service. In this example, we will use one of the services built previously:
showPhrases – Phrases from Shakespeare plays that replace the names in the phrase with the passed in name/string

This webservice requires 2 items to be passed:
id – A number from 0 to 4 (In this example I only used 5 phrases)
name – A name or variable that can be used to replace the names in the phrases

The first thing we should always do, is map out the plan for this function.

This webservice will take the ID and the name, and then return the phrase that has been ID’d, with the personalization of the name. So the first thing we need is the phrases, then we need to set up a function to do this.

So with the phrases, I took 5 different Shakespeare phrases, and removed the names, and put in a placeholder value that is uniform throughout the phrases. These phrases are listed below:

$phrases = array(
	'O NnnnnnnnnN, NnnnnnnnnN! wherefore art thou NnnnnnnnnN?',
	'But NnnnnnnnnN, If you prick us, do we not bleed? if you tickle us, do we not laugh? if you poison us, do we not die? and if you wrong us, shall we not revenge?',
	'Will all great NnnnnnnnnN\'s ocean wash this blood clean from my hand? No, this my hand will rather the multitudinous seas incarnadine, making the green one red',
	'Love looks not with the eyes, but with the mind, NnnnnnnnnN, and therefore is winged Cupid painted blind',
	'Men at some time are masters of their fates: The fault, dear NnnnnnnnnN, is not in our stars, but in ourselves, that we are underlings',
);

Next we need to create the function for this. Since this series of posts are about the webservices and not general PHP security, logic, or structure, we will quickly pass over this.
1. We want to make sure that the ID is between 0 and 4.
2. We want to replace all the placeholder values with the passed in name
3. We want to format the response to the client that lets them know it is either a success or failure

So with this function, it could look something like this:

function showPhrases($id, $name){
	// Set up the phrases
	$phrases = array(
		'O NnnnnnnnnN, NnnnnnnnnN! wherefore art thou NnnnnnnnnN?',
		'But NnnnnnnnnN, If you prick us, do we not bleed? if you tickle us, do we not laugh? if you poison us, do we not die? and if you wrong us, shall we not revenge?',
		'Will all great NnnnnnnnnN\'s ocean wash this blood clean from my hand? No, this my hand will rather the multitudinous seas incarnadine, making the green one red',
		'Love looks not with the eyes, but with the mind, NnnnnnnnnN, and therefore is winged Cupid painted blind',
		'Men at some time are masters of their fates: The fault, dear NnnnnnnnnN, is not in our stars, but in ourselves, that we are underlings',
	);

	// place all validation code here
	if ( ($id < 0) || ($id > 4)  ){
		// return an error
		$fin_data['status'] = "Error!";
		$fin_data['phrase'] = "The ID was outside of the allowed range.";
		return $fin_data;
	}

	// replace all the needles with the name
	$phrase = preg_replace("/NnnnnnnnnN/", $name, $phrases[$id]);

	$fin_data['status'] = "Success!";
	$fin_data['phrase'] = $phrase;

	return $fin_data;
}

We can do a quick test to make sure this works:

// Good call
$test1 = showPhrases(0, "HEY YOU GUYS!");
// Will return an error
$test2 = showPhrases(30, "Alexander the Great");

echo "<pre>";
print_r($test1);
print_r($test2);
echo "</pre>";

OK, we know the function works. In the real world, you would want to sanitize the string a little better and make sure there is no other attempts to grab data, or compromise your application. Now we can start to build the actual server.

We need to set up some basic stuff in the server, namely, we need to include the libraries, set the WSDL to the proper address, and register the new function. I have set this WSDL server at the following location:
http://www.hirdweb.com/webservice/20100707_server.php

$server = new soap_server();
// Create the WSDL
$wsdl_addr = 'http://www.hirdweb.com/webservice/20100707_server.php';
// Set the name that will be displayed in the WSDL, and the namespace
$server->configureWSDL('HirdWeb Basic Webservice Example','HirdWeb Basic Webservice Example', $wsdl_addr);

One of the most important things to remember when creating WSDLs, either manually (or using Zend Studio’s tool), or by using a library such as NuSOAP, is that you need to start from the bottom and work your way up. The bottom of the WSDL will always be the most base, and working up it will get more complex.

In this example, we are using a pseudo-complex/simplistic structure. The service is returning an array, but a non-complex array that does not need much, other than strings. So we need to register the function with the server first, then move to the more complex items.

First, I like to set variables for registration, this way I know what needs to go where, and what it needs to call. It is basically in this vein:
register(
    Function Name / Name of service provided
    What needs to be passed in
    What is going to be passed back
    Namespace
    SOAP Action to do this
    RPC
    Encoded / Encoding
    Documentation on this service function
)
Translating that to code, and I have this:

// Set up all the items to register the function
$in = array(
	'id' => 'xsd:string',
	'name' => 'xsd:string',
);
$out = array('return' => 'tns:showPhrases');
$namespace = 'uri:hirdwebservice';
$soapaction = 'uri:hirdwebservice/showPhrases';
$doc = 'Shows a phrase from Shakespeare and replaces the name with the supplied name. ID is a number from 0 - 4';

$server->register('showPhrases', $in, $out, $namespace, $soapaction, 'rpc', 'encoded', $doc);

Now close the service and exit so only the service is exposed.

$server->service($HTTP_RAW_POST_DATA);
exit;

But, we are not completed. If you notice the $out variable, it is setting the returned values as an array set to
tns:showPhrases

Which means we have our first complex type. If we want to just return a phrase, then we could have just left it at
xsd:string
However, I have found that by doing that, it can leave an opening in understanding what is being returned. Has the service worked, it returned a phrase, so it must be correct, right? Maybe, not sure. I always find it a good practice to make sure you tell the clients whether or not the call was successful. It just cuts down on the possibility of returning bad data.

We now have to create a type that can be returned. The naming convention should mirror that of the function. In the function, we have two named array elements:
status
phrase

We need to create a complex type that defines these elements. Using the $server object, we can add a complex type, defined as “showPhrases”. This function is called in the WSDL class:
$server->wsdl->addComplexType();
The parameters for this function are (taken straight from the code):
* @param string $name
* @param string $typeClass (complexType|simpleType|attribute)
* @param string $phpType currently supported are array and struct (php assoc array)
* @param string $compositor (all|sequence|choice)
* @param string $restrictionBase namespace:name (http://schemas.xmlsoap.org/soap/encoding/:Array)
* @param array $elements e.g. array ( name => array(name=>”,type=>”) )
* @param array $attrs e.g. array(array(‘ref’=>’SOAP-ENC:arrayType’,'wsdl:arrayType’=>’xsd:string[]‘))
* @param string $arrayType as namespace:name (xsd:string)
* @see nusoap_xmlschema
* @access public

For our complex type, we need to use the name, complexType, struct, all, ” (or default), our array setup
We will use the defaults for any items after our array.

$server->wsdl->addComplexType('showPhrases','complexType','struct','all','',
    array(
        'status' => array('name' => 'status', 'type' => 'xsd:string'),
        'phrase' => array('name' => 'message', 'type' => 'xsd:string')
    )
);

So the entire service looks like this:

// Instantiate the server
$server = new soap_server();
// Create the WSDL
$wsdl_addr = 'http://www.hirdweb.com/webservice/20100707_server.php';
$server->configureWSDL('HirdWeb Basic Webservice Example','HirdWeb Basic Webservice Example', $wsdl_addr);
$server->wsdl->addComplexType('showPhrases','complexType','struct','all','',
    array(
        'status' => array('name' => 'status', 'type' => 'xsd:string'),
        'phrase' => array('name' => 'message', 'type' => 'xsd:string')
    )
);
// Set up all the items to register the function
$in = array(
	'id' => 'xsd:string',
	'name' => 'xsd:string',
);
$out = array('return' => 'tns:showPhrases');
$namespace = 'uri:hirdwebservice';
$soapaction = 'uri:hirdwebservice/showPhrases';
$doc = 'Shows a phrase from Shakespeare and replaces the name with the supplied name. ID is a number from 0 - 4';
$server->register('showPhrases', $in, $out, $namespace, $soapaction, 'rpc', 'encoded', $doc);
$server->service($HTTP_RAW_POST_DATA);
exit; 

And now the webservice server is ready to be tested using the client, which we created a sample previously.
Make sure that you update the WSDL to point to the server we created today.
The entire file for the server, and the function can be found at
http://www.hirdweb.com/webservice/20100707_server.txt

I created a test page that will show the results of the call:
http://www.hirdweb.com/webservice/20100707.php
The client makes 6 calls to the server, 0-5. It returns 5 good results, and 1 error.

Next we will examine two services provided by a webservice service. We will have the one we created today, and add a more complex type, the showTaxes service (which we saw briefly in the client example), and expand the status message with a little more information and provide a dynamic ability for error messages.

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.