<== Lesson 1 || Overview || Lesson 3 ==>

In this lesson you will make a requests for the Mountain data from a web site. The data is returned in an XML format. Then for testing you will display the raw XML on the phone screen and also display the XML data in the XCode console.

Screen With XML Loaded From Web

The main goal is to learn to use the NSURL, NSURLRequest, NSURLConnection and NSMutableData classes.

NSURL defines a URL for XCode. NSURLConnection establishes a connection to a server and manages the data to and from that server. NSURLRequest defines a network request along with data to send. NSMutableData stores any returning data.

When you load data from the web or any indeterminate process, you will want to include an activity indicator. So we will add a UIActivityIndicatorView that is the common activity indicator for Mac applications.

To see the data on the phone screen, we will use the UITextView which is a scrollable text component. In future lessons, we will replace the UITextView with a scrolling list of mountains in the XML data we receive.

You will need a web server to complete this and all future lessons in this tutorial. The tutorials use a web server with PHP that reads a comma delimited file containing the mountain data. The XML that the PHP script returns is included in this post should you not have PHP on your server. I will show you how to use that instead of the provided PHP script. However in future lessons we will want to ask the server for just partial data and we need a program to do that. Keep in mind you can also put the mountain data into a database on the server.

Source Download

1. Starting XCode Project. This is the lesson 1 project completed.
2. PHP and CSV Files. Script to read data file and selects by elevation and returns XML.
3. Mountain XML Data. Alternative to hosting PHP script.
4. Completed XCode 4 Project

Step 1: MainViewController.h – Define properties and methods.

Download and uncompress the Starting XCode Project file and open in XCode.

Select the MainViewController.h in the project navigation window on the left and add the highlighted lines.

Line 4 is a constant for the URL to the PHP script or the XML file if you choose not to host the PHP script. More on these choices in this post when we get to those files.

The app will enable and disable the UIButton searchButton, so we need to include it for reference in code.

The UIActivityIndicatorView and UITextView are being added and are also referenced from our UI. The UIActivityIndicatorView will need to be hidden and revealed when we are not and are loading data from the server as well starting and ending its animation. So we need to make it an IBOutlet.

The UITextView will be updated with data coming in from the server and so it also needs to be an IBOutlet.

The MSMutableData is needed to capture the data coming in from the server in a raw format.

Your implementation code will call for disabling and enabling the search button and hiding and unhiding the activity indicator in more than one place in the code. Line 26 defines a method you will use so you do not have to repeat this UI state changing code in more than one place. The method receives an int parameter to define the state of the UI components. You will define their values in the implementation code.

//
//
//
#define kTextURL    @"http://YOUR_DOMAIN/PATH_IF_ANY_TO_SCRIPT/PHP_SCRIPT_OR_XML_FILE"

#import <UIKit/UIKit.h>

@interface MainViewController : UIViewController
{
    UIButton                *searchButton;
    UIActivityIndicatorView *activityIndicator;
    UITextView              *resultsTextView;

    NSURLConnection         *urlConnection;
    NSMutableData           *receivedData;

}
@property (nonatomic, retain) IBOutlet UIButton                 *searchButton;
@property (nonatomic, retain) IBOutlet UIActivityIndicatorView  *activityIndicator;
@property (nonatomic, retain) IBOutlet UITextView               *resultsTextView;

@property (nonatomic, retain) NSURLConnection *urlConnection;
@property (nonatomic, retain) NSMutableData *receivedData;

-(IBAction) startSearch:(id)sender;
- (void) setUIState:(int)uiState;
@end

Step 2: MainViewController.m – Add Properties and Constants

This step basically is the implementation housekeeping prerequisites.

You add the getter and setters for the properties on lines 4 to 9 using synthesize.

Lines 12 and 14 provide constants for states of the view that are used in the setUIState method we defined in the last step. Those places in the code can make the code more readable when calling the setUIState.

#import "MainViewController.h"

@implementation MainViewController
@synthesize searchButton;
@synthesize activityIndicator;
@synthesize resultsTextView;

@synthesize urlConnection;
@synthesize receivedData;

// State is loading data. Used to set view.
static const int LOADING_STATE = 1;
// State is active. Used to set view.
static const int ACTIVE_STATE = 0;

Step 3: MainViewController.m – Memory Management Housekeeping

Add the memory release for the searchButton, activityIndicator, activityIndicator, resultsTextView, urlConnection and receivedData in the dealloc method.

- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil
{
    self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
    if (self) {
        // Custom initialization
    }
    return self;
}

- (void)dealloc
{
    [searchButton release];
    [activityIndicator release];
    [resultsTextView release];
    [urlConnection release];
    [receivedData release];
    [super dealloc];
}

- (void)didReceiveMemoryWarning
{
    // Releases the view if it doesn't have a superview.
    [super didReceiveMemoryWarning];

    // Release any cached data, images, etc that aren't in use.
}

Step 4: MainViewController.m – Navigation Top Bar Title Updated

On line 47 you might want to update the title so you are not confused when viewing the app.

#pragma mark - View lifecycle

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view from its nib.
    [self setTitle:@"USA Mountains Lesson 2"];
}

Step 5: MainViewController.m – More Memory Management

In the viewDidUnload method add these lines to release the subviews you are going to link to this view in the UI.

- (void)viewDidUnload
{
    [super viewDidUnload];
    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
    self.searchButton = nil;
    self.activityIndicator = nil;
    self.resultsTextView = nil;
}

- (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
{
    // Return YES for supported orientations
    return (interfaceOrientation == UIInterfaceOrientationPortrait);
}

Step 6: MainViewController.m – Update the startSearch Method to Fetch Server Data

The startSearch method is already linked to our searchButton from the last tutorial. You have the code below to get the UI in the state for loading in progress, to make a request to the data source on the server and take needed steps based on the success or failure of that connection.

Line 69 is calling a method you will add in the next step to set the UI state. Your constant LOADING_STATE was defined in the last step.

Line 71 creates a NSString for the URL. In a future lesson you are going to concatenate a parameter to send along with the URL and now this line is ready for that.

The NSURLRequest object named req is created on line 74.

The instance object named urlConnection on line 77 is your NSURLConnection. It does all the work for communicating with the server.

You see on line 77 it is using our NSURLRequest req object and also sending the delegate message to make this class, self, its delegate. That means urlConnection can call NSURLConnection methods you add to this class to take action needed to handle notifications such as successful completion or failure.

For this lesson you need to add four methods to handle the NSURLConnection messages didReceiveResponse, didReceiveData, didFailWithError and connectionDidFinishLoading. You will do that just after creating our setUIState method.

Lines 79 to 83 handle a successful connection. A NSMutableData object is created and assigned to the class receivedData NSMutableData object that in later code you will convert to readable XML for display.

Should the connection fail, lines 85 to 97 display a UIAlertView with the error information. Generally you will want to change that to something more meaningful to the user.

#pragma mark - UI Interface
-(IBAction) startSearch:(id)sender
{
    NSLog(@"startSearch");
     // Change UI to loading state
    [self setUIState:LOADING_STATE];
    // Create the URL which would be http://YOUR_DOMAIN_NAME/PATH_IF_ANY_TO/get_usa_mountain_data.php?elevation=12000
    NSString *urlAsString = [NSString stringWithFormat:@"%@", kTextURL ];

    NSLog(@"urlAsString: %@",urlAsString );
    NSURLRequest *req = [[NSURLRequest alloc] initWithURL:[NSURL URLWithString:urlAsString]];
    // Create the NSURLConnection con object with the NSURLRequest req object
    // and make this MountainsEx01ViewController the delegate.
    urlConnection = [[NSURLConnection alloc] initWithRequest:req delegate:self];
    // Connection successful
    if (urlConnection) {
        NSMutableData *data = [[NSMutableData alloc] init];
        self.receivedData=data;
        [data release];
    }
    // Bad news, connection failed.
    else
    {
        UIAlertView *alert = [
                              [UIAlertView alloc]
                              initWithTitle:NSLocalizedString(@"Error", @"Error")
                              message:NSLocalizedString(@"Error connecting to remote server", @"Error connecting to remote server")
                              delegate:self
                              cancelButtonTitle:NSLocalizedString(@"Bummer", @"Bummer")
                              otherButtonTitles:nil
                              ];
        [alert show];
        [alert release];
    }
    [req release];

}

Step 7: MainViewController.m – Create the UI State Setting Method setUIState

This is your custom method to set the states of the UI components.

The UIButton has an alpha and enabled property. For your UIButton searchButtonobject, the alpha value is toggled between 50% and 100% and its enabled state is also toggled between true and false.

The UIActivityIndicatorView has methods on lines 108 and 116 for starting and stopping their animation. There is also a property hidesWhenStopped that you will set in the UI design that handles the hiding and showing of our UIActivityIndicator.

-(void) setUIState:(int)uiState;
{
    // Set view state to animating.
    if (uiState == LOADING_STATE)
    {
        searchButton.enabled = false;
        searchButton.alpha = 0.5f;
        [activityIndicator startAnimating];

    }
    // Set view state to not animating.
    else if (uiState == ACTIVE_STATE)
    {
        searchButton.enabled = true;
        searchButton.alpha = 1.0f;
        [activityIndicator stopAnimating];
    }
}

Step 8: MainViewController.m – Clear Received Data When Connection Is Established

You learned about pragma marks in the last lesson. You have 4 NSURLConnection related methods to add and this mark on line 119 is an easy way in XCode to get to where you are placing them in the code.

The connection didReceiveResponse method occurs when a connection is established. When that happens, your data communication starts over. To be on the safe side of it occurring more than once, you clear the NSMutableData object from any previous incomplete attempts. Consider this a boilerplate block you always include in code.

#pragma mark - NSURLConnection Callbacks
- (void)connection:(NSURLConnection *)connection didReceiveResponse:(NSURLResponse *)response
{
    [receivedData setLength:0];
}

Step 9: MainViewController.m – Accumulate Data Being Received

The NSURLConnection calls the connection didReceiveData method as data arrives and is ready for use. This is called as often as needed depending on the amount of data. The code you need here is to append the data received to your NSMutableData object.

- (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data
{
    [receivedData appendData:data];
}

Step 10: MainViewController.m – Handle Network Connection Failure

The connection didFailWithError NSURLConnection call back method is where you handled the failure of the data transmission. In your case the code displays a UIAlertView with information from the NSError class error object passed in for learning purposes. A better user error should be considered for a released app.

You can use the NSError class to take different action based on the type of error. This is over the scope of this tutorial.

There is some housekeeping such as calling the connection object release method and terminating the NSMutableData receivedData property.

The last line of code calls the sertUIState method with the ACTIVE_STATE value so the UI again appears available for another search.

- (void)connection:(NSURLConnection *)connection didFailWithError:(NSError *)error
{
    [connection release];
    self.receivedData = nil; 

    UIAlertView *alert = [[UIAlertView alloc]
                          initWithTitle:@"Error"
                          message:[NSString stringWithFormat:@"Connection failed! Error - %@ (URL: %@)", [error localizedDescription],[[error userInfo] objectForKey:NSURLErrorFailingURLStringErrorKey]]
                          delegate:self
                          cancelButtonTitle:@"Bummer"
                          otherButtonTitles:nil];
    [alert show];
    [alert release];
    // Change UI to active state
    [self setUIState:ACTIVE_STATE];
}

Step 11: MainViewController.m – Handle Network Connection Successful Completion

This final method is called when all the data is successfully loaded. The NSMutableData receivedData object is converted to a NSString on line 147.

On line 151 the UITextView text property resultsTextView is set to the data as a NSString. One the previous line the same is displayed in the XCode console window.

After that the NSURLConnection connection variable is released and the receivedData NSMutable object is truncated.

Your last line has the same task of setting the UI back to a state that the user can search again.

- (void)connectionDidFinishLoading:(NSURLConnection *)connection
{
    // Convert receivedData to NSString.
    NSString *receivedDataAsString = [[NSString alloc] initWithData:receivedData encoding:NSUTF8StringEncoding];

    // Trace receivedData
    NSLog(@"%s - %@", __FUNCTION__, receivedDataAsString);
    resultsTextView.text = receivedDataAsString;
    [receivedDataAsString release];

    // Connection resources release.
    [connection release];
    self.receivedData = nil;
    // Change UI to active state
    [self setUIState:ACTIVE_STATE];
}

Step 12: MainViewController.xib – Add the Activity Indicator

Open the MainViewController.xib in the Project navigator and drag an Activity Indicator from the Objects library in the bottom right to place it under the button with the Search label.

Activity Indicator View

Be sure you keep the Activity Indicator you placed selected while completing the next three tasks.

Select the size panel in the top right and set the x and y values as shown here.

Activity Indicator Size Inspector

Select the Properties inspector and set the style to Large White and check the Behavior Hides When Stopped.

Activity Indicator Properties

In the Connections Inspector panel drag from the “New Referencing Outlet” in the “Referencing Outlets” group to the File Owner’s icon and release the mouse. Then select activityIndicator. You defined activityIndicator in your MainViewController code as a UIActivityIndicatorView.

Here is how the Connections Inspector will look when you are done.

Activity Indicator Connection Inspector

Step 13: MainViewController.xib – Add the TextView

You are adding a TextView that in a future tutorial you replace with a TableView. So there is no need to get heavily invested in how it looks.

Now drag a TextView from the Objects library in the bottom right to place it under the button with the Activity Indicator.

Text View

Keep the TextView you placed selected while completing the next two tasks.

Select the size panel in the top right and set the X, Y, Width and Height values as shown here.

Text View Size Inspector

In the Connections Inspector panel drag from the “New Referencing Outlet” in the “Referencing Outlets” group to the File Owner’s icon and release the mouse. Then select resultsTextView defined activityIndicator in your MainViewController code as a UITextView.

Your Connections Inspector should appear as follows.

Text View Connection Inspector

Step 14: MainViewController.xib – Review the Changes

First you can check the layout looking as follows.

MainViewController Design Window Complete

If you select the Connections inspector and then the File Owner’s icon you should see the following. If so you are good to go.

File Owner's Connection Inspector

Step 15: PHP Server Script or XML File

This IPhone app loads XML data from a server. The Source Download includes an XML file you can use for this lesson.

However, the longer term of the Tutorial will request a query of the data from the server and at that point you can use the PHP script provided. I suggest you use that with this lesson so you are set up. But if you do not have a PHP script enabled server, you can use the XML file for a few more lessons.

Detailing how the PHP script works is beyond the scope of this tutorial. However what you should know it reads a CSV file. Here is a snippet of the file. The name used in the PHP script is mountain_data.csv.

Mount McKinley,20320, 63.0690,-151.00063
Mount Saint Elias,18008,60.2927,-140.9307
Mount Foraker,17400,62.9605,-151.3992

Then the PHP script returns XML. This is a snippet of what the XML data looks like when returned.

<?xml version="1.0" encoding="UTF-8"?>
<mountains source = "http://en.wikipedia.org/wiki/Table_of_the_highest_major_summits_of_the_United_States" elevation_min = "12000" count = "100" >
  <mountain_item id = "1" name = "Mount McKinley" elevation = "20320" lat = " 63.0690" lon = "-151.00063" />
  <mountain_item id = "2" name = "Mount Saint Elias" elevation = "18008" lat = "60.2927" lon = "-140.9307" />
  <mountain_item id = "3" name = "Mount Foraker" elevation = "17400" lat = "62.9605" lon = "-151.3992" />
</mountains>

This XML you will learn to parse in a future tutorial.

This is the PHP script. The name I used for the script was get_mountain_data.php. You can name it what you like.

<?php
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT" );
header("Last-Modified: " . gmdate( "D, d M Y H:i:s" ) . "GMT" );
header("Cache-Control: no-cache, must-revalidate" );
header("Pragma: no-cache" );
header("Content-Type: text/xml; charset=utf-8");
// XML to return.
$xml = '';
// Counter for number of mountains returned.
$mountain_count = 0;
// Filter mountains equal to or above this value.
$elevation_min = 12000;
// Check for elevation parameter as a integer.
if ($_REQUEST['elevation_min'] && intval($_REQUEST['elevation_min']))
{
	$elevation_min = intval( $_REQUEST['elevation_min']);
}
// Each element contains data for one mountain.
$mountains = array();
// Read a CVS file containing mountain data.
$mountain_data_lines = file('mountain_data.csv');
// Each line read .
foreach($mountain_data_lines as $line)
{
	// Strip newline at end of line and break line by comma delimiter and
	// append to $mountains.
	$mountains[] = explode( ',', rtrim($line));
}
// Each mountain.
foreach ($mountains as $value)
{
	// Mountain elevation equals or exceeds the filter value.
	if ( intval($value[1]) >= $elevation_min  )
	{
		$mountain_count++;
		// Create the mountain_item node.
		$xml .= '<mountain_item ';
		$xml .= 'id = "' . $mountain_count . '" ';
		$xml .= 'name = "' . $value[0] . '" ';
		$xml .= 'elevation = "' . $value[1] . '" ';
		$xml .= 'lat = "' . $value[2] . '" ';
		$xml .= 'lon = "' . $value[3] . '" ';
		$xml .= '/>';

	}
}
// Add mountains close node.
$xml .= '</mountains>';
// Create mountains open node.
$xml_mountains = '<mountains ';
$xml_mountains .= 'source = "http://en.wikipedia.org/wiki/Table_of_the_highest_major_summits_of_the_United_States" ' ;
$xml_mountains .= 'elevation_min = "' . $elevation_min . '" ';
$xml_mountains .= 'count = "' . $mountain_count . '" ';
$xml_mountains .= '>';
// Add mountains open node.
$xml = $xml_mountains . $xml;
// Return xml
echo $xml;
?>

<== Lesson 1 || Overview || Lesson 3 ==>

I chose SimpleXML simplexml_load_file method to handle the XML file and data. The problem with simplexml_load_file is that it ignores CDATA nodes. This is not immediately clear when reading the documentation. You do find references to the CDATA issue in the user comments.

The documentation also provides a hint should you decide to explore the simplexml_load_file options argument. Here you see the LIBXML_NOCDATA value which includes this explanation: “Merge CDATA as text nodes.” Using this option value converts the node containing the CDATA node into a text node using the container node name. Thus

<info>
	<![CDATA[<b>Help</b>]]>
</info>

becomes

<info>
	<b>Help</b>
</info>

This is fine since the data returning to the client is in JSON format. Here is how the solution would look:

$xml = simplexml_load_file($xml_filename, 'SimpleXMLElement', LIBXML_NOCDATA);

\n\t\t\t\t<b>help</b>

Clearly, information between nodes is NOT data. Since my goal was to have a nicely formatted XML file for a user to update manually, this created the need to strip the whitespace added.

The approach I selected was to use a regular expression to remove the whitespace characters before and after the < > tag delimters as follows:

'~\s*(<([^>]*)>[^<]*</\2>|<[^>]*>)\s*~','$1'

One caveat is that if you decide to include html in the cdata node, the regular expression removes the whitespace before and after those tags.

Also is this needs to be applied before converting to SimpleXML. So I used file_get_contents to load the xml data file, applied the regular expression and then converted to a SimpleXML object.

The completed PHP script is as follows:

<?php
// The XML data file with whitespace such as tabs
$xml_file = "user_formatted_xml_data.xml";
// Load xml data.
$xml = file_get_contents($xml_file);
// Strip whitespace between xml tags
$xml = preg_replace('~\s*(<([^>]*)>[^<]*</\2>|<[^>]*>)\s*~','$1',$xml);
// Convert CDATA into xml nodes.
$xml = simplexml_load_string($xml,'SimpleXMLElement', LIBXML_NOCDATA);
// Return JSON.
echo json_encode($xml);
?>

<?xml version="1.0" encoding="UTF-8"?>
<news_items>
	<news_item>
		<title>
			<![CDATA[News item title #1 with <br/>html added.]]>
		</title>
		<content>
			<![CDATA[This is the <b>CDATA content</b> for news item<strong> #1 </strong> with some "html" included.]]>
		</content>
	</news_item>
	<news_item>
		<title>
			<![CDATA[News item title #2 with <br/>html added.]]>
		</title>
		<content>
			<![CDATA[This is the <b>CDATA content</b> for news item<strong> #2 </strong> with some "html" included.]]>
		</content>
	</news_item>
</news_items>

After conquering a basic Parsley Framework Flex example I wanted to create a minimal example of using the Flex Parsley framework, Zend AMF and MySQL. The Flex implementation goal is to mold a model view controller framework using Parsley and to communicate via Flex RemoteObject to Zend AMF. Eventually I applied what I learned to revamp DefineIt.com with Parsley and Zend AMF.

There are many approached to using Parsley for MVC. The Parsley documentation is very light on the subject. These also entail including using other frameworks like Caringorm. In this example I kept it simply by just using the Parsley messaging features and creating my own controller class.

I found other examples of Parsley that go further into its features. You might look at Christophe Coenraets’ example. This is referenced from the Parsley documentation . Christophe includes an update and add feature to the application. It also contains a dynamically loaded image class. It is a bit over featured and thus over involved for a pure beginner. It is void of substantive explanation leaving you to explore the Parsley documentation to try to understand why one approach was chosen over another in code. Worse code has no comments. This should be a minimum requirement for any referenced sample code. However there are some good Flex and Parsley techniques in there that can be helpful and one to bookmark for your learning process.

Learn More About Flex 4 From Adobe

Parsley 2.3 is used and the SWCs are included in the example Flex 4 project download I have here. I did appreciate these SWCs also being included in the downloads from the Parsley download page. Lets you get to learning faster.

You can build this with the free Flex SDK by using the code in the src folder and be sure to include a path to the Parsley and Spicelib library.

• Flex Builder 4 Flex Project

When you run this application, the trace log will show you the interactions between the model, controller, view and service.

Application Class – Parsley_Configuration.mxml
This is the main MXML file. Line 15 links the Parsley_Configuration.mxml file that configures Parsley framework.

Line 16 tells Parsley to include this mxml file and thus allows us to inject the ApplicationModel data.

I put all locale language into the model to simplify the example. In the effort the ApplicationModel class for application level data only contains the locale language title for the application you can see referenced in the Label on lines 26 and 39.

Line 40 contains the Panel to display the data grid.

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
			   xmlns:s="library://ns.adobe.com/flex/spark"
			   xmlns:hellozend="com.alh.parsley.example.hellozend.*"
			   xmlns:parsley="http://www.spicefactory.org/parsley"
			   xmlns:mx="library://ns.adobe.com/flex/mx"
			   xmlns:sf="http://www.spicefactory.org/parsley"
			   minWidth="955" minHeight="600"
			   xmlns:views="com.alh.parsley.example.hellozend.views.*"
			   >
	<fx:Declarations>
		<!--
		Parsley configuration MXML file
		-->
		<parsley:ContextBuilder config="Parsley_Configuration" />
		<sf:Configure/>
	</fx:Declarations>
	<fx:Script>
		<![CDATA[
			import com.alh.parsley.example.hellozend.model.ApplicationModel;
			/**
			 * Parsley injects the ApplicationModel here.
			 * */
			[Inject]
			[Bindable]
			public var model:ApplicationModel;

		]]>
	</fx:Script>
	<!--
		UI
	-->
	<s:layout>
		<s:VerticalLayout gap="10"
						  horizontalAlign="center"
						  paddingLeft="12" paddingRight="12" paddingBottom="12" paddingTop="12"
						  />
	</s:layout>
	<s:Label text="{model.lang_AppTitle}" fontSize="20"/>
	<views:AllMembersGrid/>
</s:Application>

Parsley Configuration – Parsley_Configuration.mxml
This is the file Parsley reads for configuration.

I included the RemoteObject definitions here as well. I am following Christophe Coenraets’ example on this. It makes sense to me to have this as part of the configuration file. Remember to change the YOUR_GATEWAY_URL on line 13 to reflect your link to the Zend AMF or other RemoteObject service.

You may note there is no services xml or configuration file. The channel information is in the MXML instead. You can learn more on this by reading
ZEND AMF (Action Message Format) Minimalist Example Using RemoteObject and MySQL

On lines 27 – 30 I have four Actionscript classes handling the model, view and controller. They are listed here so we can use the [Inject] metatag for Parsley.

<?xml version="1.0" encoding="utf-8"?>
<Objects
	xmlns:fx="http://ns.adobe.com/mxml/2009"
	xmlns="http://www.spicefactory.org/parsley"
	xmlns:s="library://ns.adobe.com/flex/spark"
	xmlns:hellozend="com.alh.parsley.example.hellozend.*"
	xmlns:model="com.alh.parsley.example.hellozend.model.*"
	xmlns:services="com.alh.parsley.example.hellozend.services.*"
	xmlns:controller="com.alh.parsley.example.hellozend.controller.*">
	<fx:Declarations>
		<s:ChannelSet id = "zend_amf_channel_set">
			<s:channels>
				<s:AMFChannel uri="YOUR_GATEWAY_URL"/>
			</s:channels>
		</s:ChannelSet>
		<!-- MembershipService RemoteObject -->
		<s:RemoteObject	id="membershipService_ro"
						destination="zend-amf"
						source="MembershipService"
						channelSet="{zend_amf_channel_set}"
						showBusyCursor="true"
						>
		</s:RemoteObject>
		<!--
			Parsley defined objects slated for injection where [Inject] metatag appears.
		-->
		<model:ApplicationModel/>
		<model:MembershipModel/>
		<services:MembershipServiceRemote/>
		<controller:MembershipController/>
</fx:Declarations>
</Objects>

Application Model Class – ApplicationModel.as
This class defines application level data and we only have a language variable to simplify the example for localization.

package com.alh.parsley.example.hellozend.model
{
	/**
	 * Model for application level data
	 * */
	public class ApplicationModel
	{
		/**
		 * UI language in model to simplify example
		 *
		 * Language for Application
		 * */
		[Bindable]
		public var lang_AppTitle:String = "Minimalist Parsley Zend AMF Example Using RemoteObject";;
	}
}

Membership Model Class – MembershipModel.as
This class defines membership data. Again you can see the variables to simplify the example for localization.

The key data here is the ArrayCollection on line 13 for the member data.

package com.alh.parsley.example.hellozend.model
{
	import mx.collections.ArrayCollection;
	/**
	 * Model for membership
	 * */
	public class MembershipModel
	{
		/**
		 * List of members;
		 * */
		[Bindable]
		public var members:ArrayCollection;
		/**
		 * UI language in model to simplify example
		 *
		 * Language for AllMembersGrid view
		 * */
		[Bindable]
		public var lang_AllMembersGridTitle:String = "Membership Listing";
		[Bindable]
		public var lang_MemberKey:String = "Member Key";
		[Bindable]
		public var lang_FirstName:String = "First Name";
		[Bindable]
		public var lang_LastName:String = "Last Name";
		[Bindable]
		public var lang_EmailAddress:String = "Email Address";
		[Bindable]
		public var lang_GetMembers:String = "Get Members";
		[Bindable]
		public var lang_ClearMembers:String = "Clear";
	}
}

IMembershipService Class – IMembershipService.as
Interface to define methods for membership service classes. We only have one in the example: MembershipServiceRemote.

package com.alh.parsley.example.hellozend.services
{
	import mx.rpc.AsyncToken;
	/**
	 * Interface to define MembershipService classes
	 * */
	public interface IMembershipService
	{
		function getAllMembers():AsyncToken;
	}
}

Line 46 is the interface back to the MVC or to the application however you want to look at it. Here a Parsley message is created for the MembershipGetAllMembersEvent.GET_ALL_MEMBERS event that you will see the MembershipController class handles.

You could have the controller pass its own result and fault handlers to the getAllMembers() method and eliminate the MembershipGetAllMembersEvent.GET_ALL_MEMBERS message.

As a further simplification, the faults are all routed to the catchAllServiceErrorHandler(…) method where a view component is inserted breaking a clean MVC. You could create a message for the fault handler to dispatch and have the controller to handle this.

package com.alh.parsley.example.hellozend.services
{
	import com.alh.parsley.example.hellozend.events.MembershipGetAllMembersEvent;
	import com.alh.parsley.example.hellozend.services.IMembershipService;
	import mx.controls.Alert;
	import mx.rpc.AsyncResponder;
	import mx.rpc.AsyncToken;
	import mx.rpc.events.FaultEvent;
	import mx.rpc.events.ResultEvent;
	import mx.rpc.remoting.RemoteObject;
	/**
	 * IMembershipService class to handle RemoteObject data communications with server.
	 * */
	public class MembershipServiceRemote implements IMembershipService
	{
		/**
		 * Specify the remote service for Parsley to inject.
		 * */
		[Inject(id="membershipService_ro")]
		public var service:RemoteObject;
		/**
		 * Parsley creates an event dispatcher function
		 * */
		[MessageDispatcher]
		public var dispatcher:Function;

		/**
		 * Get all members from RemoteObject service.
		 * */
		public function getAllMembers():AsyncToken
		{
			trace ("SERVICE: MembershipServiceRemote.getAllMembers()");
			var token:AsyncToken = service.getAllMembers();
			token.addResponder(
				new AsyncResponder(getAllMembersResultsHandler, catchAllServiceErrorHandler));
			return token;
		}
		/**
		 * ResultEvent handler for service.getAllMembers()
		 * */
		protected function getAllMembersResultsHandler(event:ResultEvent, result:Object):void
		{
			trace ("SERVICE: MembershipServiceRemote.getAllMembersResultsHandler()");
			//event.result == Array.
			var members:Array = event.result as Array;
			dispatcher( new MembershipGetAllMembersEvent(MembershipGetAllMembersEvent.GET_ALL_MEMBERS, members));
		}
		/**
		 * Default handler for MembershipServiceRemote calls
		 * */
		protected function catchAllServiceErrorHandler(e:FaultEvent):void
		{
			Alert.show(e.toString());
		}
	}
}

MembershipController Class – MembershipController.as
This controller ties in the MembershipModel class and the MembershipServiceRemote class on line 18 and 24 respectively.

The controller listens for the MembershipEvent events on line 29. The Parsley [MessageHandler] tag makes this happen. These events are dispatched in the view.

On line 46 the controller listens for the MembershipGetAllMembersEvent dispatched from the MembershipServiceRemote class.

package com.alh.parsley.example.hellozend.controller
{
	import com.alh.parsley.example.hellozend.events.MembershipEvent;
	import com.alh.parsley.example.hellozend.events.MembershipGetAllMembersEvent;
	import com.alh.parsley.example.hellozend.model.MembershipModel;
	import com.alh.parsley.example.hellozend.services.MembershipServiceRemote;
	import mx.collections.ArrayCollection;
	/**
	 * Controller for Membership model and views.
	 * */
	public class MembershipController
	{
		/**
		 * Parsley injects the MembershipModel here.
		 * */
		[Inject]
		[Bindable]
		public var model:MembershipModel;
		/**
		 * Parsley injects the MembershipService here.
		 * */
		[Inject]
		[Bindable]
		public var service:MembershipServiceRemote;
		/**
		 * Parsley identified handler for MembershipEvent
		 * */
		[MessageHandler]
		public function membershipEventHandler( message:MembershipEvent ):void
		{
			trace ("CONTROLLER: MembershipController.membershipEventHandler(...) - message.type:" + message.type);
			switch (message.type )
			{
				case MembershipEvent.GET_ALL_MEMBERS:
					service.getAllMembers();
					break
				case MembershipEvent.CLEAR_ALL_MEMBERS:
					model.members.removeAll();
					break
			}
		}
		/**
		 * Parsley identified handler for MembershipGetAllMembersEvent
		 * */
		[MessageHandler]
		public function membershipGetAllMembersEventHandler( message:MembershipGetAllMembersEvent ):void
		{
			trace ("CONTROLLER: MembershipController.membershipGetAllMembersEventHandler(...)");
			model.members = new ArrayCollection(message.members);
		}
	}
}

Lines 27 and 28 sets up the class to dispatch Parsley messages. Line 35 dispatches the MembershipEvent.CLEAR_ALL_MEMBERS event and line 43 dispatches the MembershipEvent.GET_ALL_MEMBERS event. The MembershipController class handles these messages to update the model and communicate with the service as needed.

This view is tied to the MembershipModel class via Parsley on line 23. The DataGrid binds to the model members variable.

Other bindings for the language localizations appear as well.

<?xml version="1.0" encoding="utf-8"?>
<s:Panel xmlns:fx="http://ns.adobe.com/mxml/2009"
		 xmlns:s="library://ns.adobe.com/flex/spark"
		 xmlns:mx="library://ns.adobe.com/flex/mx"
		 xmlns:sf="http://www.spicefactory.org/parsley"
		 title = "{model.lang_AllMembersGridTitle}"
		>
	<fx:Declarations>
		<!--
		Parsely will manage this component.
		-->
		<sf:Configure/>
	</fx:Declarations>
	<fx:Script>
		<![CDATA[
			import com.alh.parsley.example.hellozend.events.MembershipEvent;
			import com.alh.parsley.example.hellozend.model.MembershipModel;
			/**
			 * Parsley injects the MembershipModel here.
			 * */
			[Inject]
			[Bindable]
			public var model:MembershipModel;
			/**
			 * Parsley creates an event dispatcher function
			 * */
			[MessageDispatcher]
			public var dispatcher:Function;
			/**
			 * Dispatch MembershipEvent.CLEAR_ALL_MEMBERS event
			 * */
			protected function clearDataGrid():void
			{
				trace("VIEW: " + className + ".clearDataGrid()");
				dispatcher( new MembershipEvent( MembershipEvent.CLEAR_ALL_MEMBERS ));
			}
			/**
			 * Dispatch MembershipEvent.GET_ALL_MEMBERS event
			 * */
			protected function getAllMembers():void
			{
				trace("VIEW: " + className + ".getAllMembers()");
				dispatcher( new MembershipEvent( MembershipEvent.GET_ALL_MEMBERS ));
			}
		]]>
	</fx:Script>
	<s:layout>
		<s:VerticalLayout gap="10"
						  paddingLeft="12" paddingRight="12" paddingBottom="12" paddingTop="12"
						  />
	</s:layout>
	<mx:DataGrid  id="member_dg"  height="100" dataProvider="{model.members}">
		<mx:columns>
			<mx:DataGridColumn headerText="{model.lang_MemberKey}" dataField="memberKey"/>
			<mx:DataGridColumn headerText="{model.lang_FirstName}" dataField="firstName"/>
			<mx:DataGridColumn headerText="{model.lang_LastName}" dataField="lastName"/>
			<mx:DataGridColumn headerText="{model.lang_EmailAddress}" dataField="emailAddress" width="200"/>
		</mx:columns>
	</mx:DataGrid>
	<s:HGroup horizontalAlign="center" width="100%">
		<s:Button label="{model.lang_GetMembers}" click="{getAllMembers();}"/>
		<s:Button label="{model.lang_ClearMembers}" click="{clearDataGrid();}"/>
	</s:HGroup>

</s:Panel>

MembershipEvent.as
This is a standard Event class to inform the MVC framework all membership data is required or needs to be cleared. These free the view from being coupled with the service or updating the model.

package com.alh.parsley.example.hellozend.events
{
	import flash.events.Event;
	/**
	 * Events related to membership.
	 * */
	public class MembershipEvent extends Event
	{
		/**
		 * Request to retrieve all membership data
		 * */
		public static const GET_ALL_MEMBERS:String = "com.alh.parsley.example.hellozend.events.MembershipEvent.getAllMembers";
		/**
		 * Request to clear all membership data
		 * */
		public static const CLEAR_ALL_MEMBERS:String = "com.alh.parsley.example.hellozend.events.MembershipEvent.clearAllMembers";

		public function MembershipEvent(type:String, bubbles:Boolean=false, cancelable:Boolean=false)
		{
			super(type, bubbles, cancelable);
		}
	}
}

MembershipGetAllMembersEvent.as
This event message signals success retrieval of members data from the service.

package com.alh.parsley.example.hellozend.events
{
	import flash.events.Event;
	/**
	 * Event defining service receipt of membership data.
	 * */
	public class MembershipGetAllMembersEvent extends Event
	{
		public static const GET_ALL_MEMBERS:String = "com.alh.parsley.example.hellozend.events.MembershipGetAllMembersEvent.getAllMembers";
		/**
		 * Membership data
		 * */
		public var members:Array;

		public function MembershipGetAllMembersEvent(type:String, members:Array, bubbles:Boolean=false, cancelable:Boolean=false)
		{
			super(type, bubbles, cancelable);
			this.members = members;
		}
	}
}

Zend AMF Gateway PHP Script
This is the gateway program for the Zend Amf. This is the file that you reference on line 13 of the Parsley_Configuration.mxml file. In this example it was named index.php.

<?php
/**
*  Sample Zend AMF gateway
*  @return Endpoint [Zend Amf Endpoint]
* */

// Configurable values
// Debugging values
$debug = true;                             // Debugging status
if ($debug)
{
	// Report all errors, warnings, interoperability and compatibility
	error_reporting(E_ALL|E_STRICT);
	// Show errors with output
	ini_set("display_errors", "on");
}
else
{
	error_reporting(0);
	ini_set("display_errors", "off");
}
// Add the Zend AMF installation folder to the include path.
// In this example the frameworks folder is a sibling folder to
// this application folder. The frameworks folder contains the Zend
// folder that is extracted from http://framework.zend.com/download/amf
ini_set("include_path", ini_get("include_path") . PATH_SEPARATOR . "..\\frameworks" );

// Instantiate the Zend Amf server
require_once 'Zend/Amf/Server.php';
$server = new Zend_Amf_Server();

// Register your service classes
require_once 'MembershipService.php';
$server->setClass("MembershipService");

//Map ActionScript value objects to the PHP value objects.
$server->setClassMap("MemberData", "MemberData");

// Return the handle.
echo ($server->handle());

?>

<?php
/**
*	Service class exposing the methods to deal with membership.
*   This example includes business logic for simplicity of study.
*/
require_once 'MemberData.php';
class MembershipService
{
	public function MembershipService()
	{
		// Connect to MySql database.
		// Supply your own MySQL access values.
		// These are defaults when running on your own private computer.
		mysql_connect("localhost", "root", "");
		// Select the database.
		// Supply your own database name.
		mysql_select_db("test");
	}
	/**
	*	Get all members and all fields.
	*/
	public function getAllMembers()
	{
		// Array of MemberData objects.
		$members = array();
		// Selecting all fields and all records from table.
		// Supply your own table name and optionally your own SQL statement.
		$result = mysql_query("SELECT * FROM zend_amf_members");
		// Assuming mysql_query success. Slog through records.
		while ($row = mysql_fetch_assoc($result))
		{
			// Create a MemberData value object and populate.
			$member = new MemberData();
			$member->memberKey = $row["memberKey"];
			$member->firstName = $row["firstName"];
			$member->lastName = $row["lastName"];
			$member->emailAddress = $row["emailAddress"];
			array_push($members, $member);
		}
		// Return the members array to client.
		return $members;
	}
}
?>

MemberData Value Object Class for PHP
This is the value object on the server side to define the field names for a member object. This is mapped to the client side on line 37 of the Zend AMF gateway script.

<?php
/**
 * Value object defining the member data
 * */
class MemberData
{
  public $memberKey;	// uint
  public $firstName;	// String
  public $lastName;		// String
  public $emailAddress;	// String
}
?>

SQL To Create Testing Table
The PHP script uses zend_amf_members for the table and this is the SQL to create that table. In this example the database was called test.

SET SQL_MODE="NO_AUTO_VALUE_ON_ZERO";

--
-- Database: `test`
--

-- --------------------------------------------------------

--
-- Table structure for table `zend_amf_members`
--

CREATE TABLE IF NOT EXISTS `zend_amf_members` (
  `memberKey` int(10) unsigned NOT NULL auto_increment,
  `firstName` varchar(30) NOT NULL default '',
  `lastName` varchar(30) NOT NULL default '',
  `emailAddress` varchar(50) NOT NULL default '',
  PRIMARY KEY  (`memberKey`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='Zend Amf Examples' AUTO_INCREMENT=7 ;

--
-- Dumping data for table `zend_amf_members`
--

INSERT INTO `zend_amf_members` (`memberKey`, `firstName`, `lastName`, `emailAddress`) VALUES
(1, 'Donald', 'Duck', 'quacker@pond.com'),
(2, 'Daffy', 'Duck', 'daft_2x@farm.org'),
(3, 'Elmer', 'Fudd', 'elmer.fudd@hunters.net'),
(4, 'Bugs', 'Bunny', 'whats_up_doc@underground.org'),
(5, 'Yosemite', 'Sam', 'varmint_chaser@forest.com'),
(6, 'Wile', 'Coyote', 'ceo@acme.com');

The first example I looked at is from Lee Brimelow’s Introduction to ZendAMF at gotoAndLearn.com. This is a great example and worth the watch to get a rounded view of using Zend AMF. He uses NetConnection and Responder classes in Flash CS4. You can use his example in Flex and Air.

Learn More About Flex 4

Eventually I put Zend AMF to practical use by revamping DefineIt.com to use it along with the Parsley framework.

Flash CS4 does not have a native RemoteObject class, so that leads us to using Flex.

Download files
You can build this with the free Flex SDK by using the code in the src folder. This example was built with Flex 4.

• Flex Builder 4 Air Project
• Flex Builder 4 Flex Project
• Zend AMF – Download and decompress into a folder on your web server. You need to adjust line 26 of the Zend AMF gateway script shown below to account for the path the Zend folder’s parent folder.

The following uses the code from the Flex example, but other than the Application and WindowedApplication tags the code is the same.

Application Class – ZendAMFRemoteObjectGetTable_Flex
Rather than use a services-config.xml file linked to the compiler line, I choose to include the channel information in the MXML. More on this method is detailed by Chris Callendar’s post Using Flex and AMFPHP without a services-config.xml file.

<?xml version="1.0" encoding="utf-8"?>
<!--
Demonstrates use of the RemoteObject to communicate with Zend AMF.
<p>Author: Lon Hosford http://www.lonhosford.com 908 996 3773</p>
-->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
			   xmlns:s="library://ns.adobe.com/flex/spark"
			   xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600">
	<fx:Declarations>
		<!-- Alternative to services-config.xml added to the compiler option services -->
		<s:ChannelSet id = "zend_amf_channel_set">
			<s:channels>
				<s:AMFChannel uri="{GATEWAY_URL}"/>
			</s:channels>
		</s:ChannelSet>
		<!-- MembershipService RemoteObject -->
		<s:RemoteObject	id="members_ro"
						destination="zend-amf"
						source="MembershipService"
						channelSet="{zend_amf_channel_set}"
						showBusyCursor="true"
						fault="membersError(event)">
			<s:method name="getAllMembers" result="getAllMembersResult(event)"/>
		</s:RemoteObject>
	</fx:Declarations>

	<fx:Script>
		<![CDATA[
			import mx.controls.Alert;
			import mx.events.FlexEvent;
			import mx.rpc.events.FaultEvent;
			import mx.rpc.events.ResultEvent;
			// [ADD YOUR HTTP URL TO THE GATEWAY PHP SCRIPT]
			private const GATEWAY_URL:String = "http://YOUR_DOMAIN/PATH_TO_GATEWAY SCRIPT/";
			/**
			 * Member value object. Not used in this example. Included for information only.
			 * Use this to convert the data received. In this example the DataGrid dataprovider
			 * property converted the incoming amf array to an ArrayCollection and we mapped
			 * using the DataGridColumn dataField property.
			 * */
			private var memberData:MemberData;
			[Bindable]
			private var lang_title:String = "Minimalist Zend AMF Example Using RemoteObject";
			/**
			 * Invoke RemoteObject members_ro getAllMembers method.
			 * */
			protected function getAllMembers():void
			{
				members_ro.getAllMembers();
			}
			/**
			 * Empties the member_dg DataGrid.
			 * */
			protected function clearDataGrid():void
			{
				member_dg.dataProvider = {};
			}
			/**
			 * RemoteObject members_ro ResultEvent handler for the remote getAllMembers method.
			 * <p>Data arrives as an array and dataProvider property converts to ArrayCollection.
			 * The member_dg DataGrid contains DataGridColumn to match the expected field using
			 * the dataField property.</p>
			 * */
			protected function getAllMembersResult(e:ResultEvent):void
			{
				member_dg.dataProvider = e.result; // ResultEvent result property is an array
			}
			/**
			 * RemoteObject members_ro default FaultEvent handler.
			 * */
			protected function membersError(e:FaultEvent):void
			{
				Alert.show(e.toString());
			}
		]]>
	</fx:Script>

	<s:VGroup horizontalAlign="center" width="100%" paddingTop="25">
		<s:Label text="{lang_title}" fontSize="20"/>

		<mx:DataGrid  id="member_dg"  height="100">
			<mx:columns>
				<mx:DataGridColumn headerText="Member Key" dataField="memberKey" width = "100"/>
				<mx:DataGridColumn headerText="First Name" dataField="firstName"/>
				<mx:DataGridColumn headerText="Last Name" dataField="lastName"/>
				<mx:DataGridColumn headerText="Email Address" dataField="emailAddress" width="200"/>
			</mx:columns>
		</mx:DataGrid>
		<s:HGroup>
			<s:Button label="Get Members" click="{getAllMembers();}"/>
			<s:Button label="Clear" click="{clearDataGrid();}"/>
		</s:HGroup>
	</s:VGroup>

</s:Application>

MemberData Value Object Class for Actionscript
This is the value object on the client side to define the field names for a member object. This is mapped to the server side on line 37 of the Zend AMF gateway script.

package
{
	/**
	 * Value object defining the member data
	 * */
	[RemoteClass(alias="MemberData")]
	[Bindable]
	public class MemberData
	{
		public var memberKey:uint;
		public var firstName:String;
		public var lastName:String;
		public var emailAddress:String;
	}
}

Zend AMF Gateway PHP Script
This is the gateway program for the Zend Amf. This is the file that is referenced on line 13 of the MXML file. In this example it was named index.php.

<?php
/**
*  Sample Zend AMF gateway
*  @return Endpoint [Zend Amf Endpoint]
* */

// Configurable values
// Debugging values
$debug = true;                             // Debugging status
if ($debug)
{
	// Report all errors, warnings, interoperability and compatibility
	error_reporting(E_ALL|E_STRICT);
	// Show errors with output
	ini_set("display_errors", "on");
}
else
{
	error_reporting(0);
	ini_set("display_errors", "off");
}
// Add the Zend AMF installation folder to the include path.
// In this example the frameworks folder is a sibling folder to
// this application folder. The frameworks folder contains the Zend
// folder that is extracted from http://framework.zend.com/download/amf
ini_set("include_path", ini_get("include_path") . PATH_SEPARATOR . "..\\frameworks" );

// Instantiate the Zend Amf server
require_once 'Zend/Amf/Server.php';
$server = new Zend_Amf_Server();

// Register your service classes
require_once 'MembershipService.php';
$server->setClass("MembershipService");

//Map ActionScript value objects to the PHP value objects.
$server->setClassMap("MemberData", "MemberData");

// Return the handle.
echo ($server->handle());

?>

<?php
/**
*	Service class exposing the methods to deal with membership.
*   This example includes business logic for simplicity of study.
*/
require_once 'MemberData.php';
class MembershipService
{
	public function MembershipService()
	{
		// Connect to MySql database.
		// Supply your own MySQL access values.
		// These are defaults when running on your own private computer.
		mysql_connect("localhost", "root", "");
		// Select the database.
		// Supply your own database name.
		mysql_select_db("test");
	}
	/**
	*	Get all members and all fields.
	*/
	public function getAllMembers()
	{
		// Array of MemberData objects.
		$members = array();
		// Selecting all fields and all records from table.
		// Supply your own table name and optionally your own SQL statement.
		$result = mysql_query("SELECT * FROM zend_amf_members");
		// Assuming mysql_query success. Slog through records.
		while ($row = mysql_fetch_assoc($result))
		{
			// Create a MemberData value object and populate.
			$member = new MemberData();
			$member->memberKey = $row["memberKey"];
			$member->firstName = $row["firstName"];
			$member->lastName = $row["lastName"];
			$member->emailAddress = $row["emailAddress"];
			array_push($members, $member);
		}
		// Return the members array to client.
		return $members;
	}
}
?>

MemberData Value Object Class for PHP
This is the value object on the server side to define the field names for a member object. This is mapped to the client side on line 37 of the Zend AMF gateway script.

<?php
/**
 * Value object defining the member data
 * */
class MemberData
{
  public $memberKey;	// uint
  public $firstName;	// String
  public $lastName;		// String
  public $emailAddress;	// String
}
?>

SQL To Create Testing Table
The PHP script uses zend_amf_members for the table and this is the SQL to create that table. In this example the database was called test.

SET SQL_MODE="NO_AUTO_VALUE_ON_ZERO";

--
-- Database: `test`
--

-- --------------------------------------------------------

--
-- Table structure for table `zend_amf_members`
--

CREATE TABLE IF NOT EXISTS `zend_amf_members` (
  `memberKey` int(10) unsigned NOT NULL auto_increment,
  `firstName` varchar(30) NOT NULL default '',
  `lastName` varchar(30) NOT NULL default '',
  `emailAddress` varchar(50) NOT NULL default '',
  PRIMARY KEY  (`memberKey`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='Zend Amf Examples' AUTO_INCREMENT=7 ;

--
-- Dumping data for table `zend_amf_members`
--

INSERT INTO `zend_amf_members` (`memberKey`, `firstName`, `lastName`, `emailAddress`) VALUES
(1, 'Donald', 'Duck', 'quacker@pond.com'),
(2, 'Daffy', 'Duck', 'daft_2x@farm.org'),
(3, 'Elmer', 'Fudd', 'elmer.fudd@hunters.net'),
(4, 'Bugs', 'Bunny', 'whats_up_doc@underground.org'),
(5, 'Yosemite', 'Sam', 'varmint_chaser@forest.com'),
(6, 'Wile', 'Coyote', 'ceo@acme.com');

I am in the process of updating my Flex Caringorm example that makes an ItemSearch operation to Amazon AWS to fetch data. AWS changed the security August 2009 to include a secret key value. Using this you need to create Signature parameter. You also need a Timestamp parameter.

The Signature parameter you need to generate and they have a utility helper to demonstrate should you need it.

There is an Actionscript example of how to generate the signed request at Brendon Wilson’s blog. I did not try it. There is a discussion in the blog comments about placing the security key in the Actionscript code. The idea of a security key implies it is to be protected. Placing it in the Actionscript code is not wise because there are tools that can open the contents of a published swf.

Another plan is to store all the AWS information on a server and place the signature code there. So this is an example on how to do that with PHP. The AWS access ID and secret key are removed from the client side and are better protected. The secert key is in plain text and as such you may want to take more action to protect that if you think the PHP script is vulnerable.

Here is the PHP version of signing an AWS request. I had to cobble various examples I found and added the references at the end of this blog article. This example designed to work with Flex HTTPService and returns XML. The script allows placing test AWS parameters in the file for testing with a browser. You might want to try other AWS operations and parameters.

Configuration is easy. Lines 9 and 10 require your AWS codes. That is it.

To generate an error from AWS keep $useTestData on line 18 as false and run the script in a web browser. Your response will show AWS balking at a missing parameter because nothing is being sent for it to process. To see a positive result change $useTestData to true and the supplied test data will produce a nice pile of XML.

<?php
/**
*  Creats AWS request and signs the request
*  Wraps AWS response in user defined XML.
*  To test add your AWS access key code ID and secrete access key and set $useTestData = true;
*/
header ("content-type: text/xml");
// Configurable values
$public_key = "{PLACE YOUR AWS ACCESS KEY HERE}";	// AWS access key code ID
$private_key = "{PLACE YOUR AWS SECRET KEY HERE}";	// AWS secret access key)
$amazonErrorRootNode = "<Errors";					// First node with < from amazon for error  response.

// Developer values
$version = "v.01.00.00";						// Version of this script

// Debugging values
$debug = false;								// Debugging status
$useTestData = false;							// Use embedded testing data

// Program controlled values
$success = "false";							// Default success value.
$params = array();							// The parameters to pass to AWS
$returnXML = "";								// XML returned

if ($useTestData)
{
	$params =  array(	"Operation"=>"ItemSearch",
                        "Keywords"=>"Beatles Abbey Road",
                        "Service"=>"AWSECommerceService",
                        "Sort"=>"salesrank",
                        "SearchIndex"=>"Music",
                        "Count"=>"25",
						"ResponseGroup"=>"Medium,Tracks,Offers");
}
else
{
	$params = $_REQUEST;
}

$returnXML .= "<response>";

$returnXML .= "<version>";
$returnXML .= $version;
$returnXML .= "</version>";
if ($debug)
{
	$returnXML .= "<isTestData>";
	$returnXML .= $useTestData ? "true":"false";
	$returnXML .= "</isTestData>";
}

function aws_signed_request( $public_key, $private_key, $params)
{
	$method = "GET";
	$host = "ecs.amazonaws.com";
	$uri = "/onca/xml";

	$timestamp = gmstrftime("%Y-%m-%dT%H:%M:%S.000Z");
	$timestamp = "&Timestamp=" . rawurlencode($timestamp);

	$params["AWSAccessKeyId"] = $public_key;

	$workurl="";
    foreach ($params as $param=>$value)
    {
		$workurl .= ((strlen($workurl) == 0)? "" : "&") . $param . "=" . rawurlencode($value);
    }
	//$workurl = str_replace(" ","%20",$workurl);
	$workurl = str_replace(",","%2C",$workurl);
	$workurl = str_replace(":","%3A",$workurl);
	$workurl .= $timestamp;
	$params = explode("&",$workurl);
	sort($params);

	$signstr = "GET\n" . $host . "\n/onca/xml\n" . implode("&",$params);
	$signstr = base64_encode(hash_hmac('sha256', $signstr, $private_key, true));
	$signstr = rawurlencode($signstr);
	$signedurl = "http://" .$host . $uri . "?" . $workurl  . "&Signature=" . $signstr;
	return $signedurl;
}

// Make the signed url for AWS
$signedurl = aws_signed_request( $public_key, $private_key, $params);

if ($debug)
{
	$returnXML .= "<signed_url>";
	$returnXML .= $signedurl;
	$returnXML .= "</signed_url>";
}

// Make request to AWS
$response = @file_get_contents($signedurl);

// The file_get_contents has failed. See PHP documentation for that.
if ($response === false) // Equal and same data type
{
	$success = "false";
}
// AWS returned a response
else
{
	$returnXML .= "<results>";
	// AWS did not return an error code
	if (strpos($response, $amazonErrorRootNode) == 0)
	{
		$success = "true";

		$returnXML .= substr($response, strpos($response, "?>")+2); // Strip Amazon XML header
	}
	// AWS returned an error code
	else
	{
		$success = "false";
		$returnXML .= substr($response, strpos($response, "?>")+2); // Strip Amazon XML header
	}
	$returnXML .= "</results>";

}

$returnXML .= "<success>";
$returnXML .= $success;
$returnXML .= "</success>";

$returnXML .= "</response>";

echo $returnXML;

?>

References

• Signing AWS requests in PHP
• Amazon® AWS HMAC signed request using PHP
• How to use the new Amazon AWS Signature in PHP
• Signing Amazon Web Service Requests in ActionScript