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.

Since this post is not about the querying of the data, that is not going to be covered, but rather just the issues with formatting the currency symbols for Euro and GBP in the Writer. And since this is not about the Spreadsheet writer ins and outs, if you would like to know more about that, please see Package Information: Spreadsheet_Excel_Writer

First off, include the PEAR library:

require_once('Spreadsheet/Excel/Writer.php');

Set up the Writer, and set the formats up.

$workbook = new Spreadsheet_Excel_Writer($this->fileSrc);
$worksheet =& $workbook->addWorksheet('Data Info');
// Set the formats for text
$formatText =& $workbook->addFormat(array('Size' => 30));
// Set the formats for two numeric values for currency
$formatUKCurr =& $workbook->addFormat(array('Size' => 12));
$formatEUROCurr =& $workbook->addFormat(array('Size' => 12));
// now we need to format the numbers
$formatUKCurr->setNumFormat('#,##0.00');
$formatEUROCurr->setNumFormat('#,##0.00');
/**
All other writer code would go here.
**/

This sets up the spreadsheet library object, added a couple of formats, and then extended it. With the numeric formats, we extended it so that the number will show up in that decimal format. What this means, is that if a number, for example 50, is retrieved from the database, then it will show up in the spreadsheet as 50.00. However, we need to put in the currency symbol in that format.

So, one would think that it would be easy enough, because all we would need to do is:

$formatUKCurr->setNumFormat('£#,##0.00');
$formatEUROCurr->setNumFormat('€#,##0.00');

Right?
Wrong. Let’s say the GBP amount is 50, and the Euro amount is 23.5. When the spreadsheet is opened in Excel, what happens to that formatting is the following:
GBP: £ 50.00
Euro: € 23.50

Yikes, there is an extra character before the pound symbol, and the Euro symbol has been warped.
1. PHP, at least not until version 6, does not support UTF-8 natively. So this means that the character set that defines these symbols is incapable of being displayed properly in the current encode that PHP understands. Thus the extra characters
2. To get more detailed info on why this character encoding is a problem, see Fun with UTF-8, PHP and MySQL. This explains a good deal about UTF-8, ASCII, and ISO 8859-1.

So the first thing I tried was to force the headers to use UTF-8. That was a no go.

The next thing was to use the ICONV.

$pound = iconv("ISO-8859-1", "UTF-8", "£");
$formatUKCurr->setNumFormat($pound . '#,##0.00');

That was a no go as well.

I changed the font family of the destination cell. That also did not work.

So I took a walk to the kitchen to clear my head. I was clearly on the wrong track. I may as well try to put everything into an array, explode it, then implode it, then echo it, then die(). So I got back from the kitchen getting some water.

The thought came to me to try using the chr() function. It could not hurt. So I looked at the PHP manual for chr() to get the ASCII code list. The code for the pound symbol according to that site, is 156, so

$formatUKCurr->setNumFormat( chr(156) . '#,##0.00' );

Well, good news and bad news. First good news, no more additional characters. Bad news, the output for the GBP was :
œ 50.00

OK, close, very close. Now I went hunting for the correct code. It is 163, so

$formatUKCurr->setNumFormat( chr(163) . '#,##0.00' );

After a couple of searches for the Euro symbol, as it is a newer symbol and not in the regular lists, I found it could be 128. So I tested it out

$formatUKCurr->setNumFormat( chr(163) . '#,##0.00' );
$formatEUROCurr->setNumFormat(  chr(128) . '#,##0.00');

And the output:
£ 50.00
€ 23.50

SUCCESS!

So, if you are struggling with this, using the Spreadsheet_Excel_Writer formatting to get the currency symbols for the GBP and the Euro, that is the fix that I have found.

First off, here is the issue. I needed to be able to export a group of records from the database to an excel spreadsheet. I have tried to use the Excel Spreadsheet add in that is listed on the Bakery. It works nice, and I had to do some modification for 1.2, but it worked. But not the way I wanted it. I have used the PEAR library Spreadsheet_Excel_Writer before and I like the type of control that I wanted, over the cells, the formatting, the merging, etc etc etc. It provides the type of control that I wanted. So here is what I did to get this to work with the CakePHP framework.

First, I have to download the PEAR library and the Spreadsheet_Excel_Writer libraries to use. Since I use a local system to help develop, I could download these libraries to the local system and transport these over to the CakePHP application. So I went to PEAR site to get the libraries. To download these I ran the following commands:

pear install PEAR-1.8.1
pear install OLE-1.0.0RC1
pear install Spreadsheet_Excel_Writer-0.9.1

URL’s are listed below:

http://pear.php.net/package/PEAR/download

http://pear.php.net/package/Spreadsheet_Excel_Writer/download

http://pear.php.net/package/OLE/download

These downloaded the to local drives and I copied them over to the CakePHP area. Here is where it gets a little tricky. And I thank “brian” who helped me on the Cake Google group to get past this when I got into a problem. So here we go, diving in to this.

First off, the PEAR libraries need to be put in the vendors directory. If you look at the directory structure for Cake, it appears like this:
/app
/cake
/vendors

Inside of the /app directory, there is another vendors directory. This is where I put the PEAR libraries. This causes problems, because in the /cake/config/paths.php file, there is a path defined for VENDORS, and for PEAR:

if (!defined('VENDORS')) {
	define('VENDORS', CAKE_CORE_INCLUDE_PATH.DS.'vendors'.DS);
}

define('PEAR', VENDORS.'Pear'.DS);

Now, I have put the PEAR libraries in the top level vendor directory. If you choose to put it in the app/vendors directory, then you may need to change a core file, which is not advisable, because you would need to change the path above to

if (!defined('VENDORS')) {
	define('VENDORS', CAKE_CORE_INCLUDE_PATH.DS.'app/vendors'.DS);
}

So back to the PEAR libraries. Here is what I needed to do. I moved the PEAR directories to the /vendors directory. So here is what that directory looks like:

/vendors
    /css
    /js
   /Pear   <--- Look at this, case sensitive based on those paths above
        /OLE
        /OS
        /PEAR
        /scripts
        /Spreadsheet
        INSTALL
        LICENSE
        OLE.php
        package.dtd
        PEAR.php
        PEAR5.php
        README
        System.php
        template.spec
    /shells

This is part of the PEAR install we need to do. Now we need to update the paths in some of these files so that CakePHP can find them and include them.

**** ORIGINAL ENTRY THAT HAS BEEN EDITED/DEPRECATED ********************
**** EDIT: Based on the original post this is the method I originally used. This way works, but requires a
**** little too much overhead and editing the files in the PEAR libraries which is never really a good idea
**** and should only be used sparingly. To see the way that it should be done, please see below this
**** section.
****
**** In the file /vendors/Pear/Spreadsheet/Excel/Writer.php there is 2 requires
**** require_once 'PEAR.php';
**** require_once 'Spreadsheet/Excel/Writer/Workbook.php';
****
**** In order for the Cake App to see these, at least in my set up, I needed to change these to the
**** following:
**** require_once 'PEAR.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Workbook.php';
****
**** I needed to add "PEAR . " to the require_once call. Now I needed to add this to the following files:
**** /vendors/Pear/Spreadsheet/Excel/Writer.php
**** require_once 'PEAR.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Workbook.php';
****
**** /vendors/Pear/Spreadsheet/Excel/Writer/Workbook.php
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Format.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/BIFFwriter.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Worksheet.php';
**** require_once PEAR . 'Spreadsheet/Excel/Writer/Parser.php';
**** require_once PEAR . 'OLE/PPS/Root.php';
**** require_once PEAR . 'OLE/PPS/File.php';
****
**** /vendors/Pear/OLE/PPS.php
**** require_once 'PEAR.php';
**** require_once PEAR . 'OLE.php';
****
**** This had helped the application find my PEAR libraries when trying to do this
**** END ORIGINAL ENTRY ***********************************************

Now, a word about the edit. The above method works, but is not a preferred method. The best method for this, so there is no need to edit PEAR library files is the following. And a big thanks to Daniel Hofstetter for pointing this out.

I put this at the top of my controller file. I am sure there is better places for this, probably even the app_controller file so that all controllers get the needed include path set. Here is what I did.

I needed to append the include path so that the new PEAR path would be found. After the php opening, I added this line:

ini_set("include_path", PEAR . PATH_SEPARATOR . ini_get("include_path"));

I am going to go over this just a little. First off, the ini_set is called to set the include_path. But we do not want to destroy any other include paths that are set up as well. So when we add the PEAR path, we need to also include the other paths as well. So the initial include_path was as follows (given in example form only, where the directory "test" is where I have CakePHP installed)
ini_get("include_path") =

/www/htdocs/html/test:/www/htdocs/html/test/app/:.:/usr/local/php5/lib/php

Since CakePHP already defines the variable for the PEAR path as "PEAR", we can use that to add to the include path, like shown above. After setting the path using ini_set(), we run ini_get("include_path") it would =

/www/htdocs/html/test/vendors/Pear/:/www/htdocs/html/test:/www/htdocs/html/test/app/:.:/usr/local/php5/lib/php

By doing it this way, there is no need to edit the PEAR library files, and we can add new PEAR libraries without having to worry about editing those files as well.

Now, I needed to make the controller aware of the vendor library. In my controller file I added this line before the class declaration:

App::import('vendor', 'Spreadsheet_Excel_Writer', array('file' => '../vendors/Pear/Spreadsheet/Excel/Writer.php'));

In Cake 1.2, this is how the vendor's are imported. The vendor() declaration has been deprecated. This imports a vendor, gives the class a name (I choose the base one that it is usually called), and the location of the of the file. In my set up, I needed to add the "../", you may not have to.

In the function, (I called "export"), I did not want to have a "view" page for it. The first thing I did was grab the information I needed. For this example, I needed all users that signed up for a conference. So I grabbed that information and put it in an array $registrations.

function export ($id = null){
       // I only want to get a specific conference, not all of them
	if ( $id == 'all' ){
		$this->Session->setFlash('Please select a specific conference to export the registrations.');
		$this->redirect(array('action' => 'index'));
	}

	// Now get the registrations for the conference
	$registrations = $this->Registration->find('all',
		array(
			'conditions' => array('conference_id' => $id),
			'fields' => array('*'),
			'recursive' => '-1',
			'order' => array('Registration.created'),
		)
	);

Now comes the fun part, building the column heading array, and then instantiating the writer

	// Set up the header array
	$titles = array(
		'Name' => 15,
		'Address' => 20,
		'City' => 20,
		'State' => 7,
		'Zip Code' => 10,
		'Email' => 20,
		'Phone' => 13,
	);

	$rn = 0; // row number
	// Build the XLS file using PEAR
	$xlsBook = new Spreadsheet_Excel_Writer();
	$xlsBook->send("registrations.xls");
	$xls =& $xlsBook->addWorksheet('Registrations');

Everything else is now just as the same as it would be with the Spreadsheet-Excel_writer. Create the formats as you would like, for text, numerics, specialized strings, colors, etc. Write the sheet headings, if you so desire

	/* Create styles for the spreadsheet */
	$format_bold =& $xlsBook->addFormat();
	$format_bold->setBold();

	$main =& $xlsBook->addFormat(
		array('Size' => 14,
			'Align' => 'center',
			'Color' => 'black',
			'Bold' => 'true'
		));
	$main->setBold();

	$formatText =& $xlsBook->addFormat(array('Size' => 11));

	$cn = 0;
	$xls->write($rn, 0, "CONFERENCE REGISTRATIONS", $main);
	$xls->mergeCells($rn,0,$rn,11);
	$rn++;

As you can see, just use the writer calls to write the data, format it, and do what you need. To get more information on this, please check the PEAR documentation for this library.

Finish up the column headings by doing a quick little loop

	// Set up the headings of the columns
	foreach ( $titles as $t => $val){
		$xls->setColumn($cn, $cn, $val);
		$xls->write($rn, $cn++, $t, $format_bold);
	}
	$rn++;
	// reset the column num
	$cn = 0;

Now you can do the actual rows in a loop:

	foreach ( $registrations as $r ){
		$xls->write($rn, $cn++, $r['Registration']['name'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['address'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['city'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['state'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['zip_code'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['email'], $formatText);
	    $xls->write($rn, $cn++, $r['Registration']['contact_phone1'], $formatText);
	    // cycle to the next row
	    $rn++;
	    // Reset the column
	    $cn = 0;
	}

	$xlsBook->close();
	exit();
} // end of function

Now, this does the work for me on my code. To call it in the view, I have a page that shows all registrations on the page, the function name is "registrations". I set a variable in this function for the ID number to be passed to the view. In the view for this function, I have put the following:

if ( $param != 'all') {
	echo "<p><br />&nbsp; &nbsp; &nbsp; - - <b>";
	echo $html->link(__('EXPORT DATA', true), array('action' => 'export', $param) );
	echo "</b> - - <br /><br /></p>";
}

So I want a specific conference. If there is not one, and they are viewing all registrations for all conferences, then it does not show the link. But if it is a specific id, then it shows the link to export with the corresponding parameter for the ID.

And there it is. Using the Spreadsheet_Excel_Writer PEAR library with CakePHP 1.2.

Again, this works for me, and there may be a better way of doing things, and if so, please feel free to tell me. I am always looking for new things to learn.

Here is the book I bought:
iPhone Development
by Dave Mark and Jeff LaMarche
Apress

Not sure when I will have time to get through this. But I will. Also, if there are any other books, or better resources to look at, please let me know. There are a few apps I have in mind for all portable/phone devices I want to do, but as with the rest of the world, money is a little tight right now and have to start somewhere.

This is a very useful tool, and if you look at the PHP manual for ereg(), it states that the function “preg_match” is a faster alternative to “ereg()”. Now while I am not going to get into the details of the speed and response times for both functions, as there will always be someone with a different opinion or case that shows how their way is better, and that is fine. What most people have a hard time dealing with is getting the actual match to do what is needed. There are times when It is just easier to do a Google search and get some code that someone else has already done and plug it in. But the real power is knowing what you are doing first, that way you can build your own.

For this example, we can take a look at CakePHP’s own little validation object. When you set up a model and add some validation to it, it calls this object. Based on the data that this going into the tables, it will call one of these functions. The way these functions work is by checking the input for a specific character list/set that should be contained in the text. If the entry does not match up, then it is not validated. The way CakePHp does this is by using the preg_match() function.

If you are new to regular expressions, then seeing something like this:

define('VALID_EMAIL', "/^[a-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+(?:[a-z]{2,4}|museum|travel)$/i");

may be a little scary. But never fear, this is not as bad as it seems. It just looks real scary. And besides, even Cake made it a little better.

So let’s look at this function:

function email($check, $deep = false, $regex = null) {
. . .
	if (is_null($_this->regex)) {
		$_this->regex = '/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)*@' . $_this->__pattern['hostname'] . '$/i';
	}
	$return = $_this->_check();
. . .
}

function _check() {
. . .
	if (preg_match($_this->regex, $_this->check)) {
		$_this->error[] = false;
		return true;
	} else {
		$_this->error[] = true;
		return false;
	}
}

If you would like to know more about the function, then please browse to the CakePHP manual to get more info about that function, since all this is going to do is point out the regex part of it.

First off, the function called is “email”. In this function, there is a regex match set that is the following:
‘/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)*@’ . $_this->__pattern['hostname'] . ‘$/i’

It passes that to the _check() function, which puts this regex pattern to the email address that is entered to see if there is a match. So to jump ahead if someone were to put in an email address of:
– flavio@nothing.com
It would pass that function. (NOTE: this does not mean it is a valid email address that can recieve emails, it just means that the characters in the email address are in the valid format of (address_name)@(hostname).(Extension) )

But this also means that someone could put in the email address:
– flavio@nothing.show
And that would pass as well, while the following email addresses:
– flavio
– flavio@nothing
– flavioATnothingDOTcom
would fail.

But now that we know that, how did we get there?

Let’s break down the match.

The first thing, we are looking for a pattern, so we need to ad the following:
/ /
around the pattern. This is a Perl syntax that is followed for finding patterns. Now the bookends come, with the caret ( ^) and the dollar sign ( $ ). The caret means to search the beginning of the string for the pattern, and the dollar sign matches the end of the string. In this example, the caret matches the first part of the email address entered, and the dollar sign matches the end.

'/^[ ]$/'

So we are off to a good start. but there since we are looking for a pattern that does not need to be case sensitive, as we do not care if there are uppercase letters or not, we need to add an “i” at the end.

'/^[ ]$/i'

Now we are ready to start looking at the beginning of the string. We are going to put this in a bracket to group the characters, or create a class. We want to get any valid characters for an email address. This would include any letters, numbers and some special characters. We will need to escape some of these (using the “\” to escape)

'/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]$/i'

This will now look for the address name, sort of. As long as there are no periods in the address account name, it will work, but there are addresses out there that have a “.” in it:
– flavio.elguappo@nothing.com
would not pass the validation as of yet (given that we would have also added the domain by the time it is checked).

So we need to add that match set in to the expression. CakePHP does this by using an atomic grouping. Using the parenthesis usually means that a “backreference” should be done. You can escape this by using “?:”. The question mark-colon combo after the first parenthesis signifies that what is coming is not a backreference. Now, to get the addresses that have a period in the account name we add this:
(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)

As you can see, this is almost the same pattern as before. We want to check the same things again after any appearance of a period. So now it looks like:

'/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)$/i'

Last things here, we need to account for the @ symbol in the address, and add the domain name. Since CakePHP already takes care of that, they have there own addition:

'/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)*@' . $_this->__pattern['hostname'] . '$/i'

And the final php code would be as follows:

$checked = preg_match('/^[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+\/=?^_`{|}~-]+)*@' . $_this->__pattern['hostname'] . '$/i', $email_address_to_check);

return $checked;

Now I am sure I glossed over some regex rules and explanations. I will never claim to be an expert on regex, as I am still learning as much as I can about this. Now this is not the only way to check an email address. If you do not use CakePHP and the real nifty built in helper, then you can use this one:

"/^[^0-9][A-z0-9_]+([.][A-z0-9_]+)*[@][A-z0-9_]+([.][A-z0-9_]+)*[.][A-z]{2,4}$/"

This one is similar, check the account name for valid characters, see if it has any periods in the name, check the @ symbol and then check the domain name, and then the domain extension, allowing for 2-4 characters in the extension.

And if you want to get some real good info on other regex info, here are a couple of links I found useful:
http://www.webcheatsheet.com/php/regular_expressions.php
http://www.regular-expressions.info/tutorial.html
http://us3.php.net/manual/en/function.preg-match.php
(Make sure you read the comments as they have some good info)

// Controller file
$eng = $this->Users->Select("language", "English");
$spn = $this->Users->Select("language", "Spanish");
$gmn = $this->Users->Select("language", "German");
$fre = $this->Users->Select("language", "French");

**Note this is not using any kind of construct in CakePHP, Symfony or any particular framework, just an example of a User class with a function called Select passing in 2 variables.

As an example, the view of this same code may be something like:

// Controller File
$this->set('lang', array($eng, $spn, $gmn, $fre);

Now while this may work for the time being, it could cause a hassle later on if there are more languages that the application will need to support.

Now, this is not saying that the above example is bad practice, because it is entirely possible that it will only need these two languages. Like if you were programming an application for a Canadian business, it would need to have both English and French. There may never be a requirement for Spanish, German, or any other language. What I am doing more of now, is making things more dynamic, to handle new items seamlessly and with little new code.

Taking the above example, we could put it into something like so:

// Model File
class User extends someBaseModelObject {
. . .
function getLanguages(){
      $langs = array(
          "English", "German", "Spanish", "French"
      );
      return $langs;
}

// Controller File
$langs = $this->User->getLanguages();

$this->set('lang', $langs);

Now if there is a new language, all that needs to be updated is the Model file instead of adding new lines of code to one part, updating another line of code in another part, and so on.

Is this possibly an oversimplification of this idea? Yes it is. But I do not write this as a simplification, but to just show something I am starting to focus on more, is that I need to make things more dynamic so I do not have to re-do code as new things are added. I use language as an example in this post, because that is just an easy example to show. There are many things that could be done for dynamic purposes. It is all about thinking about the right way to code.

Since this will be a comparison, most of the ideas will revolve around the tutorials that each camp has created. Plus, I will be only looking at the latest stable versions, so they are:
CakePHP: 1.2.1.8004
Symfony: 1.2

Each have their own tutorials, and they are at the following:
Symfony: Jobeet Tutorial, using Propel.
CakePHP: CakePHP Blog

First off, about the tutorials.
I really do think that Symfony has a better tutorial. It is a lot more intensive and sometimes confusing, which means it also goes more in depth about what this framework can do, and how to do it. This tutorial also brings in a good deal of real world dilemmas.

CakePHP’s blog tutorial is just a standard blog tutorial, which everyone seems to have anymore. It is a good tutorial, and it does show off some real good aspects of the framework, but it really does lack some of the “gotchas” that would really happen in the real world.

Installation Process and Upgrade
Symfony – Getting Symfony is pretty easy. You can download it from the site in a “sandbox” form. It is pretty easy and able to do much right from the download. But what makes this framework so wonderful about getting it, is that you can use PEAR to download it. By following the detailed installation instructions, there are a few different ways to install this. If you have the PEAR libraries, it makes it very easy to install and upgrade.

CakePHP – Getting CakePHP is also easy. While it does not have a PEAR installation path, the zip file is available in many forms, like .zip, or .gz, bz2, or .dmg. After you unzip the file, just plop it in the web accessible document root. It will work right out of the box provided on most systems. It is supposed to work right away with mod_rewrite, so certain Windows systems may have issues. (However, I have loaded it on a Windows Vista system and it worked ok, so take that for what it is worth). The directory structure allows it to work right away as is. However, the webroot app can be moved outside the normal directory structure to make a different configuration. Upgrading can be done as well, usually by overwriting the /cake directory.

But as with everything, always follow directions on upgrading. Very important.

Basic Ideals Behind the Framework
Symfony – Using a basic MVC (Model-View-Controller) design theory, it really does separate the logic portions of the application. By using the built in view, it keeps the majority of the PHP out of the HTML area. The models use more of a YAML approach to build the data objectivity. YAML (YAML Ain’t a Markup Language, morphed from Yet Another Markup Language). It can use Propel or Doctrine to help in this. The Jobeet tutorial I used was the Propel version. The controller is a standard idea of what you would expect in a controller.

CakePHP – Uses a MVC design theory, and really follows the same patterns. The real strength of CakePHP, at least to me, is it does not mess around with another version of data markup, like YAML. Some people like it, I do not prefer it. So to me this is better. However, the model also provides a real easy way to provide data validation for each row in the table. By using basic PHP concepts, you can set up validation for inserts and/or updates. The view is a little less robust than the Symfony version. While it does help with different pages/views, the framework does have a little too much reliance on php generated code. However, it does have excellent helpers to help generate HTML, forms, tables, etc.

Routing and Fancy URLs
Symfony – By updating the file: apps/frontend/config/routing.yml (yes it uses another YAML format) you can route certain calls to certain pages. However, this makes it real easy to create Fancy URLs in which the URL actually has some real data in it instead of something like : ‘jobs/2/34′.

CakePHP – In order to create Fancy URLs, CakePHP needs to have the default routes updated. While it is not as easy as it is in Symfony, it is possible. By using the detailed instructions in the Cookbook, you can set this up to have the nice URLs.

Command Line Interface Utilities
Symfony – Now while this is not an instructional post on how to use each CLI, I must say, I like the Symfony version a lot better. While it is clean and real forthcoming, there is a lot you can do with it. Combine that with the Propel and you have a really good CLI tool to help with the application.

CakePHP – The CLI in CakePHP leaves a little to be desired. While it is very helpful in creating the Models, the Controllers, and the Views, it really does not do as much. But for CakePHP this is actually ok. There are a lot of things to do with the CLI, but not as much as Symfony has.

Configuration
Symfony – Symfony seems to thrive on configurations for some reason. There is a whole directory dedicated to just config files. To me this seems a bit of overkill to do it this way. However, with the way Symfony is laid out, it works this way. There are different things to configure, and following the instructions is key. Especially since these files are read from top to bottom, so if you have a custom config in the routes after the default entry, it will never find the custom one.

CakePHP – There is also a full directory dedicated to configurations as well, but less files to parse through. Some may say this is a bad thing, some may say this is a good thing. The main files to look at are the core.php and database.php files. The routes.php file is also useful, but all in all, less config files to deal with.

Naming Conventions
Instead of separating this area, it is important to note that with each framework, there is a reason behind the madness with naming conventions. By adhering to these conventions, the framework works a lot better and can do a lot more.

In Symfony there is more leeway with file names, tables, etc.

In CakePHP they are a bit more strict, but these conventions can also be bent to suit the needs.

Core Components
Symfony – There is a good deal of components in this framework, and they all have a set purpose. Instead of matching each one as a 1:1 deal, it is important to go over the usability of these components. In Symfony, there are good ones to help paginate, create sessions, scaffold an application and even do security. Using these is easy, and this is one area where both frameworks excel.

CakePHP – Again, this is a great area for both frameworks. While in CakePHP, the components are not limited to the core ones, but can be extended (as in Symfony), they are very useful in helping create the application. These components are very helpful and can be a boon to even the novice programmer.

Both of these frameworks use these components to help speed the application up while not giving in to shoddy work.

Testing
Symfony – The great thing about Symfony, is that it has a built in testing platform. The testing platform it includes is Lime. This is a great boost to development. Now while writing the application, you can actually write the test first, then the application to make sure you know which area needs more attention. Both Unit and Functional testing is handled, and can work with others like PHPUnit and Selenium.

CakePHP – one of the great things about this framework, is that you can choose which testing platform to use. The drawback to that is, you do not get a testing platform with the package. However, it is encouraged to use SimpleTest to do this. Installation is another step, but it helps to test the application. Writing the tests is a little more than what it takes in Symfony, however, I also believe that it does testing better than Symfony.

Security
Here is a question for any and all frameworks. How secure is it? well this can be answered with the following question:
How secure are you writing this application?

Even though Symfony and CakePHP provide good methods, components and helpers to handle securing your application, you have to use these, and use them correctly. Both proved ACL implementations, data validation and sanitation and much more to help secure the app. For any one to make a statement that one framework is more secure than the other, is just not getting the point of security.

Documentation
Symfony – By far, this is the more documented framework. I have been able to find a ton of information on Symfony questions. The documentation in the cookbook is solid, and the tutorial is better than anything I have seen from other frameworks. There are other groups, IRC channels and other avenues to explore to help you get the info you need.

CakePHP – This framework is still coming of age. So the documentation is not always complete and not always found right away. There are groups, IRC channels and other avenues to get this information, just not as plentiful. However, that will change very shortly. With a stronger emphasis on community events and community submissions, this framework could easily have a plethora od documentation avenues by next year.

**NOTE: The following is based on my own personal experience.
As mentioned in the comments below, CakePHP does have stats to show it is bigger and more popular than Symfony. Please see Nate’s comments below for the links.

Community
Symfony – With many sites already using Symfony, the community is growing like wildfire. It was already a very abundant community, with many people helping and contributing. As with every open source project, it is only as strong as its community, which is very active.

CakePHP – This is the up and comer. Not quite as widespread as Symfony, but it has it very loyal followers. There are many ways that a community member can help out (and not just by donating), and this community is really rising fast to help meet the demand for more events and more documentation.

Final Analysis
While I will not give a clear cut answer as to which is the better framework, because the best solution is the solution that will meet the needs of the business/client/etc. Sometimes that may be Symfony, sometimes it may be CakePHP. Sometimes it may just be .ASPX. But there is no real clear cut winner in my mind.

I have used both frameworks to develop applications. Some of them huge, some of them small. I find CakePHP easier to start up from the ground up. And I find the extensibility of Symfony really helpful in certain apps that require a lot of redundant user input. Both frameworks are great. I would use both of them all the time for different things.

Which also means that I am no expert in either one. Since I spend time in both frameworks, I know what I like and do not like about each of them. I would also wager to say that no one is really an expert in either framework, unless you are the main developer of that project. What I am presenting is the different aspects I have found from my development standpoint. Some may see things missing in this list, which I am sure there are. These are some of the things to decide when trying to figure out if a framework will help you. Some developers also are of the opinion that no framework is good and would rather develop from scratch. That is fine too. Remember that the best solution to the problem, is the solution that solves the main crux of the problem.