“marks the end of the active support for PHP 5.2. Following this release the PHP 5.2 series will receive no further active bug maintenance. Security fixes for PHP 5.2 might be published on a case by cases basis. All users of PHP 5.2 are encouraged to upgrade to PHP 5.3.”

There are a lot of different applications that are just now adopting 5.2, and it will not be actively supported.

Marco Tabini posted a really great article on this, and I highly suggest to review this. It is located at his blog: blog.tabini.ca. While Marco makes great points in his article, the comments on the article are also a good thing to read.

One idea that is important to remember, is that 5.3 will (in theory) work even if the code was made for 5.2. This is of course, the code is well written. But that is the case no matter what code or library, or base you may use. That is the most important aspect, write good code. However, by not providing support when a possible major group of users come on board, can be risky. However, this is where the whole argument of open source and paid services can come back to play in political office meeting rooms.

Paid services, like Microsoft’s .NET libraries for example, are expensive, but are still supported. Sure it is expensive. Think of this in an enterprise application environment. A company has invested a lot of man hours on a major project upgrade (from 4 to 5.2 for whatever reason they had to stay at 4 for the time), and then find out that the major project they undertook to move to 5.2 will now need further evaluation to determine if 5.3 is acceptable to the company. More cost of investing time, energy, resources, and money can be a huge thing when the “powers that be” decide if they want to continue to use open source for their applications.

I know this is a very simplistic example, and there are even more questions with this, like if it was an enterprise app why did it stay on php4 for so long. But since 5.3 has been out for a little over a year, it seems shocking that they would be so quickly retiring active support for this.

It may have more to do with other things, including shelving PHP6. I am not as worried about 5.2 retiring. But it is an interesting event. Some will say this is really nothing, and that there is really nothing to this. And they may be entirely correct.

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.

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.

It may seem like I am talking about lol-catz, which I am not. This is the code we do inside of our code. It extends beyond the logic of the code, or hopefully it does. If your own little code defies all logic, then maybe the code will break hard one day. This code is our own little way of saying how we are putting the code together. This is the notes/documentation that we write (or fail to write), the variable naming convention, object/function naming, any user messages we write, and error trapping/error handling we do. And there is more, this is just a few of the things that we get to write our own “code”.

One of the funniest things for me to do is to go back and look at some of my very first code. I look at the documentation I did, and it is funny to read. Some of the things I actually am scratching my head wondering what I was meaning half the time. The variables have great names which only partially tell what they were supposed to be doing. And the best is looking at the old VB 6 code where the variables followed the Microsoft horrendous naming structure.

Why do I write this and not about real code? Because there will be a time that you will be on both sides, writing and reading, and before you get upset that the person previous to you did not know what they were doing, they probably did. They wrote their non-code code perfectly for them and may have even understood their words at one time. And as sure as that will happen, you will write something that someone else will come in and scratch their head and say “What?”

So take it all in stride. Laugh about it, decipher it, and go forward. There is not enough time in the day to sit and stew about bad code/bad documentation/bad variable naming/bad non-code code.

And next post, I really do promise I will write more about actual code.