Leveraging Zend Framework Components from Adobe Flash Platform Applications

One of the most useful concepts in software development is the practice of creating modular, reusable
code. As a developer, you’re likely familiar with the heartache of reinventing the wheel. Doing so is
certainly sometimes necessary, but when it isn’t, you would be well served by using plug-and-play
components.

One problem that often arises when using your own modular components is that they haven’t been
thoroughly tested, and the responsibility for their function rests solely on you—the creator. So, if
there is a bug, you end up backtracking through every project that uses that code. As a result, many
developers turn to third-party modules supported by an active community or corporate ownership. Each
has distinct advantages and disadvantages: An active community drives rapid development and copious
amounts of user-generated documentation, but the ultimate responsibility for the quality of the
software may end up on you—the component’s user. Commercial code has one ultimately accountable entity
but can be expensive and restrictively licensed. However, as an Adobe Flex and PHP developer, you don’t
have to choose between flexibility and dependability.

Zend Technologies, PHP’s corporate sponsor, is also the sponsor of the open source Zend Framework, a
collection of free, reusable PHP modules. And, as of version 1.7, Zend Framework includes an extension
for native Adobe Action Message Format (AMF) communication between Adobe Flash Platform applications
and PHP. The Zend Framework has not only a committed corporate sponsor but also an active developer
community, and it is widely used in production environments. This doesn’t mean that there are no bugs,
but you can be confident that when problems do arise, the community and Zend are dedicated to
addressing them.

The Zend Framework includes extensions for a vast array of common programming tasks, including database
connectivity and abstraction, e-mail, authentication, and third-party application programming interface
(API) access. Most of these are useful in Flex applications, and with Zend_Amf, leveraging them has
never been easier. In this article, you create a Flex application that takes advantage of some useful
Zend Framework extensions. Using Zend_Amf, the Community Volunteer Flex application will:

1. use Zend_Db to store persistent data in a MySQL database.
2. validate respondents using a Zend_Captcha image.
3. notify the volunteer coordinator using Zend_Mail.

To create this application, you need the following tools:

1. Adobe Flex Builder version 3.0.2 or later or Zend Studio for Eclipse version 6.1.1 or later
   with the Flex Builder version 3.0.2 or later Eclipse plug-in, which is the recommended option (See
   the article,
   “Integrated
   PHP and Flex development with Zend Studio and Flex Builder,” for setup
   instructions.)
2. A web server with PHP version 5 and MySQL version 5 installed
3. The GD PHP extension to generate images
4. Zend Framework version 1.7.3 or later

Note: The application and code presented here are for educational and testing purposes and should not
be used unmodified in a production environment.

The Community Volunteer Application

The Community Volunteer application is fairly straightforward, and creating it serves as a good
introduction to some of the most popular extensions of the Zend Framework. You’ll be using Flex Builder
to create a Flash Platform client, and the Zend Framework helps form the PHP back-end services. Figure
1 shows the basic application flow, assuming success at each juncture.

Figure 1. Basic application flow

As you can see, the client application and PHP services do all the heavy lifting, and the user has only
to complete the form and submit it. The whole volunteer sign-up process should take between one and two
minutes, with no more than 3–5 seconds of “processing time.” The rich client you create in Flex helps
to ensure that any data-entry errors are caught and corrected before the server-side code swings into
action.

The Community Volunteer application uses a custom object, the Volunteer. You can use custom objects
across Flex and PHP to ensure data integrity and business rules. The Volunteer object has the following
attributes:

1. id. An auto-incremented integer
2. f_name. The volunteer’s first name
3. l_name. The volunteer’s last name
4. email. The volunteer’s e-mail address
5. phone. The volunteer’s phone number
6. hpw. The volunteer’s desired number of hours of service per week
7. avail_days. The days the volunteer is available
8. special_skills. Any skills the volunteer may have that would benefit the organization

These attributes will be reflected in the MySQL database. In this article, the database is called vols,
and the table of volunteers is called volunteers. This Structured Query Language (SQL) script sets up a
table of sample values in your database:

CREATE TABLE `volunteers` (
  `id` int(5) NOT NULL auto_increment,
  `f_name` varchar(55) NOT NULL,
  `l_name` varchar(55) NOT NULL,
  `email` varchar(75) NOT NULL,
  `phone` varchar(15) NOT NULL,
  `hpw` int(3) NOT NULL,
  `avail_days` varchar(135) NOT NULL,
  `special_skills` text,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM  DEFAULT CHARSET=latin1 AUTO_INCREMENT=4 ;

INSERT INTO `volunteers` (`id`, `f_name`, `l_name`, `email`,
        `phone`, `hpw`, `avail_days`, `special_skills`) 
    VALUES(1, 'Richard', 'Bates', 'richard@flexandair.com',
        '706-555-7100', 8, 'Monday, Tuesday. Thursday',
        'Absolutely none');
        
INSERT INTO `volunteers` (`id`, `f_name`, `l_name`, `email`,
        `phone`, `hpw`, `avail_days`, `special_skills`) 
    VALUES(2, 'Vicky', 'Vol', 'vicky@ivolunteer.fake',
        '212-555-1212', 6, 'Monday, Wednesday, Friday',
        'Experienced typing teacher');
        
INSERT INTO `volunteers` (`id`, `f_name`, `l_name`, `email`,
        `phone`, `hpw`, `avail_days`, `special_skills`) 
    VALUES(3, 'Jimmy', 'Offershelp', 'jimmy@email.bogus',
        '338-555-1212', 10, 'Tuesday, Saturday',
        'Certified welder');

After you’ve set up your database, you’re ready to start on the PHP services.

Creating the PHP Services

The first step in setting up the PHP needed for the Community Volunteer application is obtaining the
Zend Framework. Navigate to the Zend Framework website, and click Download Now. The page that follows
presents several options, but this article assumes that you’re using the full Zend Framework version
1.7.3. Figure 2 shows the appropriate download link.

Figure 2. Downloading the Zend Framework

You’ll need to sign into your Zend account or create one at no cost. When the download is complete,
extract the downloaded archive to a convenient location. The result should look similar to Figure 3.

Figure 3. File structure of the installed Zend Framework

Next, navigate to the web root folder of your web server. For example, if you’re using WAMPServer on
Windows, the default web root is C:\wamp\www; for MAMP on the Mac, the default web root is
Applications/MAMP/htdocs. Within this folder, create a new directory named Vols. This folder will be
the base directory for your Community Volunteer application. If you’re using Windows, copy the folder
named library from the Zend Framework download (see Figure 3) into the directory containing your web
root folder. If you’re using WAMPServer, the default is C:\wamp. If you’re using MAMP on a Mac, the
MAMP folder already contains a library directory. In this case, copy the /Zend subfolder to the
MAMP/Library directory to enable your application to use components from the Zend Framework.

Set Up the Directory Structure

Finally, you need to set up the directory structure of the application. Within the Vols folder, create
a new directory called include. Then, open the new include folder and create a folder called services.
Figure 4 illustrates the proper resulting structure.

Figure 4. Proper directory structure for your application

Write the PHP Code

With the folders in place, its time to begin writing the PHP code. This article assumes that you’re
using Zend Studio for Eclipse version 6.1.1. First, click File > New Project. For the project name,
type services, then clear the Use Default check box. In the Directory box, type the path to your Web
Root/Vols/include/services folder. Figure 5 shows the correct settings on a Mac using MAMP web server.

Figure 5. Setting up your project

Click Finish; your new project appears in the left pane of Zend Studio. The first file you create
defines the Volunteer object. To create this file, right-click the services folder, and then choose New
> Folder. In the New Folder dialog box, name the folder VO. Next, right-click the VO folder, then
choose New > PHP File. In the dialog box that appears, type the file name Volunteer.php, and then click
Finish. The file opens in the editor pane of Zend Studio. The contents of the Volunteer.php file are
sparse and simple:

<?php
class Volunteer {
    public $id = null;
    public $f_name = '';
    public $l_name = '';
    public $email = '';
    public $phone = '';
    public $hpw = '';
    public $avail_days = '';
    public $special_skills = '';
}
?>

The file simply declares the class and enumerates the variables you need to access from your services,
which correspond directly to the column names in the MySQL database. Save and close the file, then
create another new PHP file in the /services folder. Name this file DBConnection.php. You use this file
to store the database connection details and make the connection available to other services. First,
you need to make sure you have access to the required Zend Framework files. There are several ways to
include the Zend Framework: This article uses a set_include_path statement later to load the needed
files. This method is not the most convenient if you plan on permanently installing the Zend Framework
for use in several projects, but it is useful for accessing the Framework components as needed. For
built-in access to the Zend Framework in multiple projects, you need to add the /library folder to your
PHP include path. For more information on this and other options, see the Zend Framework Documentation.

DBConnection.php uses Zend_Db. To include this extension, begin your file with an include statement:

<?php
include 'Zend/Db.php';

Be sure to adjust this line to reflect your Zend Framework location. Next, declare your DBConnection
class:

class DBConnection {

Then, you need to create a function to connect to a MySQL database and return that connection so it can
be used elsewhere. Call that function getConnection():

function getConnection() {

To begin the function, you need to instantiate a new Zend_Db::factory object. Pass two arguments to the
new factory: the database driver to be used and an array containing the connection details and
credentials. This example uses the Pdo_Mysql driver and connects to the default installation of MySQL
under MAMP on the Mac. Using Windows and WAMPServer, you’ll need to change the MySQL password to
your value.

$db = Zend_Db::factory('Pdo_Mysql', array(
            'host'     => 'localhost',
            'username' => 'root',
            'password' => 'root',
            'dbname'   => 'vols'
        )); 

Finally, this function needs to return the connection so that your other services can use it:

return $db;
    }
}
?>

Be sure to add the closing brackets (}) and tag (?>) to the class, function, and <?php block.

Create the Service for the Flex Client

Now that you’ve defined the Volunteer object and your database connection, you’re ready to create a
service that the Flex client can use. Again, create a new PHP file in the services folder. Name this
one DBService.php. Begin the code by including the files you just created: Volunteer.php and
DBConnection.php. Then, declare the DBService class:

<?php
include 'DBConnection.php';
include 'VO/Volunteer.php';
class DBService {

Because these files are in the same directory as the DBService file, it’s both safe and logical to use
the relative paths in the include statements.

It’s always a good idea to document your classes with PHPDoc blocks. Not only will they help you and
other developers navigate your code, but they’ll also help to provide more debugging information for
some errors. The first function in the DBService class will be for saving new volunteers to the
database, so it needs to accept a Volunteer object. It will also return a string. To reflect this, add
a PHPDoc block like the following:

/**
* save a new volunteer
*
* @param Volunteer
* @return string
**/

Next, declare the saveVol() function, and assign a variable to the passed-in Volunteer object:

function saveVol(Volunteer $newVol) {

Then, get a connection to the database using the DBConnection class’s getConnection() method:

$db = DBConnection::getConnection();

You’ll need to populate a data object with the properties from the volunteer that the client passes in.
This enables you to perform an insert using Zend_Db:

$data = array(
            'f_name' => $newVol->f_name,
            'l_name' => $newVol->l_name,
            'email'  => $newVol->email,
            'phone' => $newVol->phone,
            'hpw' => $newVol->hpw,
            'avail_days' => $newVol->avail_days,
            'special_skills' => $newVol->special_skills
         );
$db->insert('vols', $data);

As you can see, the insert() function accepts the database table name as the first argument and the new
record’s information as the second argument. Finally, return a string to let the client know the
insertion was a success, then close out the code:

return "OK";
    }    
}
?>

Make the Service Available to Your Application

You now have all the basic parts of a Zend_Amf–compatible service. To make this service available to your applications, you’ll also need a gateway file. The gateway file instantiates the Zend_Amf server and passes it information about your services and custom objects. To create the gateway file in Zend Studio, click File > New > PHP File. For the file’s location, type the application’s base directory, Vols. This folder should be inside your web server’s web root. Then, name the file gateway.php and click Finish.

Begin the gateway file’s code with an include path declaration like this one:

<?php
if(set_include_path('/Applications/MAMP/Library/') === false){
die('Include path failed');
}

Again, be sure to change the path to match your setup, if necessary. Next, require_once the Zend_Amf
server file and your DBService class:

require_once 'Zend/Amf/Server.php';
require_once 'include/services/DBService.php';

These next lines instantiate the server and tell it that the DBService class should be exposed. The
latter is accomplished using the server’s setClass() method:

// Instantiate the server
$server = new Zend_Amf_Server();
$server->setClass('DBService');

Map Your Classes

Next, you map the Volunteer class to the class you’ll use in ActionScript on the Flex client. Call your
class VolunteerVO, and set its mapping with the server’s setClassMap() method, passing in the
ActionScript class name first and the PHP class name second:

$server->setClassMap('VolunteerVO', 'Volunteer');

The final lines of the gateway file instruct the server on what it should accept and what it should
return:

$server->setProduction(false);
$response = $server->handle();
echo $response;
?>

The setProduction() function is set to False, which causes the server’s output to be more verbose. This
is useful during testing, but this function should never be set to False if the server is publicly
available; the debugging information is more than you would want to share with the whole Internet.
Next, assign the variable $response to the server’s handle() method to instruct the server to handle
the request. Finally, the response is echoed back to the client. Be sure to add this part, because
without it, your clients will not get a response.

Figure 6 shows how your files and folders should now be arranged.

Figure 6. The file structure as it currently stands

Test Your Work

To test your work so far, open a web browser and navigate to http://localhost/Vols/gateway.php. You
should see something similar to Figure 7.

Figure 7. Testing your application

Your browser may prompt you to download a file instead of displaying “Zend Amf Endpoint,” and that is
also a successful test. If neither of those events happens, review your code and check your PHP error
log for problems. If your test was successful, you’re ready to add the Captcha service.

Generating Captcha Images for Use in a Flash Platform Client

If you’ve filled out online forms or commented on a blog, you’ve probably used Captcha before. It’s the
little image with the garbled letters and numbers with a text box for you to type what you see. Captcha
stands for “Completely Automated Public Turing test to tell Computers and Humans Apart.” This mechanism
keeps spam bots from auto-filling forms with junk. You’ll be using Captcha to generate dynamic images
with PHP, then display them in a Flex application.

To begin, create a new PHP file in your services folder in Zend Studio. Name the file
CaptchaService.php. Inside the blank file, start by including two Zend Framework files:

<?php
include 'Zend/Captcha/Image.php';
include 'Zend/Session/Namespace.php';

The Image.php file contains the code for generating Captcha images; the Namespace.php file enables you
to keep track of which images were shown to a particular visitor. Next, declare the CaptchaService
class and its first function, generate(). Then, instantiate a new Zend_Captcha_Image to the variable
$captcha:

class CaptchaService {
/**
* generate a captcha image
*
* @return string
**/
    function generate() {
    
          $captcha = new Zend_Captcha_Image(); // new instance

Now, you need to pass some parameters to the $captcha object:

$captcha->setTimeout('300')
   ->setWordLen('6') // give us 6 letters
       ->setHeight('80')
       ->setFont('../../include/batm.ttf') // path to your font
       ->setImgDir('../../captcha');   // where the image is stored

You’ll need a TrueType font to generate the Captcha image. In this case, I’m using the batm.ttf font,
which is in the Vols/include folder. You’ll also need a directory in which to store the images that
Zend_Captcha generates. Create the captcha folder in the main Vols directory, and make sure it’s
writable by your web server. The easiest way to do this is to grant Write access to Everyone on Windows
and Mac. On Linux, set the captcha folder’s permissions to 777. Your directory and files should now be
arranged like Figure 8.

Figure 8. The Captcha directory structure

Back in your CaptchaService.php file, complete the generate() function with the following lines:

$captcha->generate() //actually generate the image and session ID
return $captcha->getId();
    
}   //end function generate

The getId() method returns the session ID, which is also the name of the generated image file. You’ll
use this ID to both display the image and compare the user’s input to the correct answer with the
validate() function:

/**
* validate a captcha
*
* @param array
* @return string
**/
    function validate($info) {    
        $response['id'] = $info[0];
        $response['input'] = $info[1];

This function begins by accepting an array, $info, which contains the session ID and the user’s answer
to the Captcha challenge. These pieces of information are assigned to key–value pairs in the $response
variable. Next, you need to get a new instance of Zend_Captcha_Image:

$captcha = new Zend_Captcha_Image(); // new instance

When the $captcha variable is initialized, its isValid() method is used to check the user’s input.
You’ll need to pass in the $response variable containing the session ID and user input so that the
Captcha Image class can determine the correct response:

if($captcha->isValid($response)) {
              // All good.
              return "OK";
          }
          else {
              // Doesn’t match
              return "NOMATCH";
          }
Finally, close the function, class, and <?php tag:

    }
}
?>

Now that your CaptchaService.php file is complete, you can add it to the services that Zend_Amf
exposes. To do this, go back to your gateway.php file and add another require_once below the
others—this time for CaptchaService.php:

require_once 'include/services/CaptchaService.php';

Then, add an additional call to $server->setClass below the others:

$server->setClass('CaptchaService');

The information you’ll be passing between the client and the CaptchaService class is pretty basic and
doesn’t need a custom class or $server->setClassMap(), so the two lines above are all that is needed.

Sending E-mail Using Zend_Mail

The Zend_Mail extension makes sending e-mail messages through PHP incredibly easy. Only a few
parameters are required, and most would be hard-coded in a typical PHP script. However, so this example
can be extended, I walk through creating an Email class and sending an entire e-mail object to the
class for processing. To begin, right-click the /services/VO folder in Zend Studio’s left pane once
again, then choose New > PHP File. Name this file Email.php. Just as in your Volunteer.php file, you
use this file to enumerate the properties of the object. The complete contents of the file should be:

<?php
class Email {
    public $body = '';
    public $from = '';
    public $recipient = '';
    public $subject = '';
}
?>

Save this file, then create another new file in the /services folder called EmailService.php. Before
you declare the EmailService class, add your include statements for the custom Email object and the
Zend_Mail extension:

include 'VO/Email.php';
include 'Zend/Mail.php';

Next, declare the class and add the PHPDoc block for the sole function you’ll be creating, sendEmail():

class EmailService {

/**
* send an email using sendmail
* @param Email
* @return String
**/

The sendEmail() function accepts an Email object as a parameter and returns a string to let the client
know that it is complete. Here is the sendEmail function:

function sendEmail(Email $email) {
        $mail = new Zend_Mail();
        $mail->setBodyText($email->body);
        $mail->setFrom($email->from);
        $mail->addTo($email->recipient);
        $mail->setSubject($email->subject);
        $mail->send();
        return "OK";
    }
}
?>

The function begins by creating a new instance of Zend_Mail. Then, the mail object is populated with
the values from the object that was passed in. Finally, the send() method is invoked, and the string OK
is returned. To complete the file, add the closing tags and save it.

Once again, you’ll need to tell the Zend_Amf server to expose this class and how to map the Email
object. Back in your gateway.php file, add another require_once statement:

require_once 'include/services/EmailService.php';

Then, add the necessary setClass() call:

$server->setClass('EmailService');

And finally, map the Email class in PHP to the EmailVO class in ActionScript:

$server->setClassMap('EmailVO', 'Email');

Save the file, and your PHP work is complete. You’re ready to move on to the Flex client.

Creating the Flash Platform Client with Flex Builder

If you’re using the recommended setup, you’ll have Flex Builder installed as a plug-in for Zend Studio
for Eclipse. However, to begin working with Flex projects, you may have to switch perspectives in Zend
Studio from PHP to Flex Development. To do this, click Window > Open Perspective > Other. Then, choose
Flex Development from the dialog box.

There are two ways to create the Flex client in Zend Studio. One method is to add the Flex Nature to
the project by right-clicking the main project folder and choosing Flex Project Nature > Add Flex
Project Nature. The other method is to create a new Flex project by selecting File > New > Flex
Project. If you are building a PHP/Flex project in Zend Studio, it may be more convenient to use the
first method. However, if you use a different integrated development environment (IDE) for the PHP
portion of your project, you’ll have to create a new project in Flex Builder. The steps for both
methods are almost identical, but this article creates a new Flex project, because it works regardless
of the PHP IDE used.

To create a new Flex project, click File > New > Flex Project. In the dialog box that appears, name
your project Vols, then change the Application server type to PHP and click Next. In the next dialog
box, enter the appropriate details for your server. You can use any directory within your web root.
Figure 9 shows appropriate settings for MAMP on Mac.

Figure 9. Server details for MAMP on Mac

When you’re done, click Finish; the new project appears in the workspace. If you’re using all the
defaults, your Navigator pane on the left should look like Figure 10.

Figure 10. Navigator hierarchy for your new project

The first thing you’ll want to do is create custom ActionScript class files that correspond to the
Email.php and Volunteer.php classes. Start by expanding the Vols project folder; then, right-click the
src subfolder and choose New > Folder. When you create custom classes in ActionScript, like many other
languages, the protocol is to use dot-syntax to avoid confusion. It is also accepted practice to use
domain names, as they are a handy way of ensuring uniqueness. Because I own the domain name
flexandair.com, I’ll create the folder structure com/flexandair/ and place my custom classes in the
flexandair folder. For convenience, you’ll want to do the same for this exercise. The classes can then
be accessed in ActionScript by importing them from com.flexandair.MyClass. To set this up in your
project, you can enter the full path in the New Folder dialog box: /com/flexandair. Click Finish, and
both directories will be created.

Next, right-click the flexandair folder, then choose New > ActionScript Class. For the class name,
type VolunteerVO. Click Finish, and the basic class file is generated. The first things you’ll
need to add to this file are the [Bindable] tag and an alias definition for class mapping. Add these
two lines right below the package declaration and opening bracket, on lines 3 and 4:

[Bindable]
[RemoteClass(alias="VolunteerVO")]

The [Bindable] tag simply allows data binding to this class’s properties. The next line is to
indicate that this class is mapped remotely as VolunteerVO. Next, you need to add the same properties
here in ActionScript that you added before to the Volunteer.php file. Add these lines right below the
class declaration and opening bracket, before the VolunteerVO constructor function:

public var id:int = 0;
public var f_name:String = '';
public var l_name:String = '';
public var email:String = '';
public var phone:String = '';
public var hpw:Number = 0;
public var avail_days:String = '';
public var special_skills:String = '';

Save the file, and create another ActionScript class called EmailVO, also in the flexandair folder.
Repeat the steps above, this time adding this code to lines 3 and 4:

[Bindable]
[RemoteClass(alias="EmailVO")]

Then, add the corresponding properties within the opening class declaration:

public var body:String = '';
public var from:String = '';
public var recipient:String = '';
public var subject:String = '';

Save the file, and your custom ActionScript classes are complete. Next, you need to tell your Flex
application how to reach your Zend_Amf server. The services-config.xml file is an Extensible Markup
Language (XML) document that specifies the properties of the remote services your application will use.
To create this file, right-click the src folder of your Flex project, then choose New > File. Name
the file services-config.xml, then click Finish. You’ll be presented with the new empty file. The
default editor is the built-in XML editor, but you need to open it in the plain text editor by
right-clicking the file and choosing Open with > Text Editor. Next, paste the following code into
the file:

<?xml version="1.0" encoding="utf-8"?>
<services-config>
    <services>
        <service id="amf-remoting" class="flex.messaging.services.RemotingService" messageTypes="flex.messaging.messages.RemotingMessage">
            <destination id="zend_amf">
                <channels>
                    <channel ref="my-zend_amf"/>
                </channels>
            </destination>
        </service>
    </services>
    <channels>
        <channel-definition id="my-zend_amf" class="mx.messaging.channels.AMFChannel">
            <endpoint uri="http://localhost/Vols/gateway.php" class="flex.messaging.endpoints.AMFEndpoint"/>
        </channel-definition>
    </channels>
</services-config>

The above XML block contains two key pieces of information specific to this application. The first is
the id attribute of the <destination> node. You’ll use this ID to connect to the remote
service in the Flex application. The other important attribute is the uri property of the
<endpoint> node. Here, you need to place the path to your Zend_Amf gateway file on your web
server. The class attributes correspond to the method of communication: you’ll be using
“remoting” to communicate with your services in AMF.

Next, you need to tell the Flex compiler about your services-config.xml file. You do so using the
compiler flag -services. To add this flag, click Project > Properties. A new window appears with a
list on the left side. From that list, choose Flex Compiler. At the end of the existing text in the
Additional compiler arguments box, add the following:

-services “services-config.xml”

The result should look like Figure 11.

Figure 11. Adding compiler arguments

Click Finish, and the workspace refreshes. When complete, you’ll have access to your Zend_Amf
gateway from the client application.

Building the Client Application

To start building the client application, open the main application file, Vols.mxml. MXML is a markup
language similar to XML or Hypertext Markup Language (HTML) used primarily for creating user interface
(UI) controls in Flex.

Line 2 of the Vols.mxml file contains the opening <mx:Application> tag and sets some of the
application’s properties. Change the layout property from layout="absolute" to
layout="vertical", which arranges your components vertically—handy for applications in
which specifying the coordinates of everything on the screen isn’t necessary. Next, move down
below the <mx:Application> tag. Here, you’ll create remote objects. Remote objects are used
to access services exposed by Zend_Amf or other AMF gateways. First, create the opening tag of the
CaptchaService remote object:

<mx:RemoteObject id="captchaService" destination="zend_amf" source="CaptchaService">

This opening tag specifies several attributes:

1. Id. This ID must be unique within the Flex application, and it allows you to reference this remote object elsewhere in the code.
• Note: I’m using the same names here as in the PHP file and class names and changing the first letter to lowercase. You can use any ID you like: Just bear in mind that you don’t have to match the MXML ID with the PHP class name. The source property must match the PHP class name (see below).
2. Destination. This is the destination ID you specified in the services-config.xml file. Make sure this matches exactly.
3. Source. This is the name of the PHP class you’re accessing through this remote object. This name must match the class name in your PHP code.

Specify Your Services

Next, you need to specify the services you want to access through the remote object—in other words, the methods you created in the CaptchaService class. Create the generate() method first:

<mx:method name="generate" result="onCaptchaGenerated()"fault="onFault(event)" />

The <mx:method> tag also contains some important attributes:

1. Name. This is the name of the method in PHP. Be sure to set the name of the method exactly as it is specified in your CaptchaService.php file.
2. Result. When the method returns a result, this ActionScript function (which you’ll create momentarily) will be called.
3. Fault. In the event of a fault, the onFault() function is called. Notice that you are passing the event itself to the onFault() function. You’ll also create this function in a moment.

Notice that this opening <mx:method> tag is closed with the shorthand />. Remember, the
<mx:RemoteObject> tag has not yet been closed, and this method is being placed within the remote
object tags. Before you close the <mx:RemoteObject> tag, insert another <mx:method>, this
time for the validate() method:

<mx:method name="validate" result="onValidateResult()" fault="onFault(event)" />

Now, add the closing </mx:RemoteObject> tag:

</mx:RemoteObject>

You’ll need to create remote objects and methods for the other services—EmailService and
DBService—as well. Below is the code for these. Always make sure you specify a unique ID each
time and that your method names and source attributes match the PHP function and class names,
respectively:

<mx:RemoteObject id="dbService" destination="Zend_Amf" source="DBService">
    <mx:method name="saveVol" result="onVolSaved()" fault="onFault(event)" />
</mx:RemoteObject>

<mx:RemoteObject id="emailService" destination="Zend_Amf" source="EmailService">
    <mx:method name="sendEmail" result="onEmailSent()" fault="onFault(event)" />
</mx:RemoteObject>

Lay Out the Visual Components

Next, start laying out the visual components of the application by adding a label:

<mx:Label text="New Volunteer Signup Form" fontSize="14"/>

You’ll also need a form for the user to enter the required information. Forms are very easy to
create using Flex Builder’s visual designer; the code that follows was created in Design mode.
Below the code, I discuss the individual elements.

<mx:Form height="356" horizontalScrollPolicy="off" verticalScrollPolicy="off">
        <mx:FormItem label="First Name">
            <mx:TextInput width="181" id="fNameInput"/>
        </mx:FormItem>
        <mx:FormItem label="Last Name">
            <mx:TextInput width="181" id="lNameInput"/>
        </mx:FormItem>
        <mx:FormItem label="Email">
            <mx:TextInput width="181" id="emailInput"/>
        </mx:FormItem>
        <mx:FormItem label="Phone">
            <mx:TextInput width="181" id="phoneInput"/>
        </mx:FormItem>
        <mx:FormItem label="Hours Per Week">
            <mx:TextInput width="181" id="hpwInput"/>
        </mx:FormItem>
        <mx:FormItem horizontalAlign="left" label="Available Days" height="89" width="297" horizontalScrollPolicy="off">
            <mx:Canvas width="184" height="83" id="daysForm">
                <mx:CheckBox label="Monday" x="10"/>
                <mx:CheckBox label="Tuesday" x="108"/>
                <mx:CheckBox label="Wednesday" x="10" y="19"/>
                <mx:CheckBox label="Thursday" x="108" y="19"/>
                <mx:CheckBox label="Friday" x="10" y="40"/>
                <mx:CheckBox label="Saturday" x="108" y="40"/>
                <mx:CheckBox label="Sunday" x="10" y="61"/>
            </mx:Canvas>
        </mx:FormItem>
        <mx:FormItem label="Special Skills?" height="93">
            <mx:TextArea height="93" width="182" id="skillsInput"/>
        </mx:FormItem>
    </mx:Form>

Now, that’s a lot of code, but it’s pretty straightforward. In fact, it should look
familiar if you work with HTML. Let’s examine one of the text inputs—a single-line entry
box with a label:

<mx:FormItem label="First Name">
    <mx:TextInput width="181" id="fNameInput"/>
</mx:FormItem>

As you can see, an <mx:FormItem> tag encapsulates each control on the form. Then, the
label’s text property is set. Next, the input portion of the form item, in this case a
TextInput, is placed within the <mx:FormItem> tag. The width is set, and a unique ID is
specified. The ID allows you to access the component elsewhere in the code. Each TextInput in the form
follows this example.

Next is a more complicated component: a set of check boxes that allow the user to select all the days
of the week he or she is available. The check boxes are inside an <mx:Canvas> tag, which allows
you to rearrange them to take up less space without the application forcing them into the default
vertical layout:

<mx:FormItem horizontalAlign="left" label="Available Days" height="89" width="297" horizontalScrollPolicy="off">
    <mx:Canvas width="184" height="83" id="daysForm">
        <mx:CheckBox label="Monday" x="10"/>
        <mx:CheckBox label="Tuesday" x="108"/>
        <mx:CheckBox label="Wednesday" x="10" y="19"/>
        <mx:CheckBox label="Thursday" x="108" y="19"/>
        <mx:CheckBox label="Friday" x="10" y="40"/>
        <mx:CheckBox label="Saturday" x="108" y="40"/>
        <mx:CheckBox label="Sunday" x="10" y="61"/>
    </mx:Canvas>
</mx:FormItem>

You’ll also notice that properties called horizontalScrollPolicy and verticalScrollPolicy are
sometimes set to Off. This simply means that even though your components may be very close to the
borders of their parent containers, you still don’t want scrollbars created.

Next, add controls for the Captcha image and the user’s response. Add these below the
form’s closing tag:

<mx:Image id="captchaImage"/>
<mx:Label text="Please enter the characters you see in the box below"/>
<mx:TextInput id="captchaInput"/>

The image control is used, predictably, to display images. However, you would normally set a URL where
the image is located using the source property. You don’t do that here, because the Captcha
image is dynamically created for each session. Finally, add a Submit button so that all your grand
designs can start swinging into motion:

<mx:Button label="Submit" click="validate()"/>

Write the ActionScript Functions

Now that all the required user controls are in place, you can proceed to writing the ActionScript
functions. ActionScript works with MXML in Flex applications in a conceptually similar way to HTML
with JavaScript code. In Flex, you need to place your ActionScript code inside an <mx:Script>
block. Start typing this tag below the <mx:Button> tag for the Submit button. Use Flex
Builder’s auto-complete function, and it should generate the basic ActionScript block, which
begins like this:

<mx:Script>
        <![CDATA[

The CDATA tag simply tells the Flex compiler that what follows is ActionScript, not MXML. Right below
the CDATA tag, you need to add some import statements for the classes you’ll be using in the
application:

import mx.controls.CheckBox; // checkbox control class
import mx.rpc.events.FaultEvent; // fault events thrown by remote objects
import mx.controls.Alert; // pop-up alerts
import com.flexandair.VolunteerVO; // custom VolunteerVO object
import com.flexandair.EmailVO;// custom EmailVO object

Now, you need to create two variables here before you write any functions. These variables will be
accessible for all the functions that follow. You’ll also precede them with a [Bindable] tag to
enable data binding:

[Bindable]
private var sessionID:String = '';
private var vol:VolunteerVO = new VolunteerVO();

The sessionID string holds the string returned by the captchaService’s generate() method. It
will be used to display the Captcha image and to verify the response. The vol:VolunteerVO object holds
the visitor’s information from the form in its properties. When the user submits the form, this
object will be passed to the Zend_Amf gateway.

The first function you’ll create is the onCaptchaGenerated() function. This function is set to
be called on the captchaService.generate() method’s result event:

private function onCaptchaGenerated():void {
sessionID = captchaService.generate.lastResult;
    captchaImage.source = "http://localhost/Vols/captcha/" + sessionID + ".png";
}

The first thing that takes place here is that the sessionID is set to a value returned by Zend_Amf
from the generate() function in PHP. Next, that value is used to create the URL to the Captcha image.
Make sure this path leads to the /captcha images folder on your web server. The extension .png is
appended, because that is the format of the Captcha image; as of this writing, PNG is
Zend_Captcha_Image’s only supported output format. This URL is assigned to the source property
of the captchaImage control you created in MXML a moment ago. Now, the entry form will show the
appropriate Captcha image to the user.

To check the user’s input, create a validate() function:

private function validate():void {
    var info:Array = new Array();
    info[0] = sessionID;
    info[1] = captchaInput.text;
    captchaService.validate(info);
} 

In the validate() function, the first line creates a new array. The sessionID and the user’s
Captcha response are then placed in the array. Because the Captcha response text input has an ID of
captchaInput, you access the contents of the text input using captchaInput.text. Finally, the array is
sent to the Zend_Amf gateway, ultimately destined for the validate() method in CaptchaService.php. All
of your Zend_Amf remote methods will be accessed this way, using the format
RemoteObjectID.remoteMethodName(infoToPassIn).

The next step is to bind the user’s input to a new VolunteerVO object so that his or her details
can be sent to PHP and saved in the database. To keep it simple, you’ll be chaining all the
ActionScript functions together, with each function predicated on the success of the previous one. To
do this, use the validate() remote method’s result event to trigger the next step, sending a new
volunteer to the database. If the Captcha validation comes back as OK, the new VolunteerVO will go to
the DBService class in PHP:

private function onValidateResult():void {
    if (captchaService.validate.lastResult == "OK") {
        //Proceed                                
        vol.f_name = fNameInput.text;
        vol.l_name = lNameInput.text;
        vol.email = emailInput.text;
        vol.phone = phoneInput.text;
        vol.hpw = Number(hpwInput.text);
        vol.avail_days = listDays();
        vol.special_skills = skillsInput.text;
        dbService.saveVol(vol);
    }
    else {
        //incorrect
        Alert.show("No Good","BAD");
        captchaService.generate();
        captchaInput.text= '';
    }
}

The if statement in ActionScript is similar to the one in PHP. If the result is OK, the values from
the form are collected and placed in a new VolunteerVO object. The hpw variable is a number, but
<mx:TextInput> controls store everything in the text property as a string. Therefore, you need
to use the Number(string) function to convert the type. Finally, the dbService.saveVol() remote method
is called, with the new VolunteerVO being passed in.

If the user’s response to the Captcha is incorrect, a new image is produced and the text box
cleared, allowing the user to try again. Again, the remote method for generating a new Captcha image
is accessed using the format RemoteObjectID.remoteMethodName(). Recall that the onCaptchaGenerated()
function is triggered after the new image and session are created, therefore updating the image URL
and the sessionID.

Also notice that the avail_days property is set by another function, listDays(). The listDays()
function goes through all the check boxes, assembling a list of the selected days. By list, I mean a
human list, not a programming data type. The day names are placed into a single string, separated by
commas and spaces. Let’s go through the listDays() function:

private function listDays():String {
    var days:String = ""; // holds the day names
    var i:int = 0; // lets us know if this is the first day selected
    for each (var cb:CheckBox in daysForm.getChildren()) {// daysForm contains all the day checkboxes
        if (cb.selected == true) { // checkbox is checked
            if (i == 0) { // item is first checked item
                days += cb.label; // just add the name only, no commas or spaces
            }
            else { // not the first item
                days += ", " + cb.label; // prefix with comma and space to build list
            }
            i++; // increment placeholder
        }                
    }
    return days; // return the list of selected days
}

The function begins by creating a local variable, days, in which to store the string containing the
selected days. Next, a placeholder variable, i, is declared. Keeping track of the iteration number in
the loop enables you to properly place the commas and spaces. Then, the loop begins. Because all of
the check boxes are in an <mx:Canvas> tag with the ID daysForm, you can use
daysForm.getChildren() to get an array containing all of them. For each check box that is a child of
daysForm, the loop tests whether the box is selected. If it is, the loop tests i. If i=0, you know
that this box is the first selected check box. Because you wouldn’t begin a list with a comma
and a space, you simply add the check box’s label to the days string. If, however, i > 0, the
selected day is not the first and should be preceded by a comma and space and appended to the list. At
the end of the loop, the placeholder is incremented, and when all the check boxes have been tested,
the list string is returned. The days string looks something like Monday, Wednesday, Sunday (depending
on the days selected).

Working with the Results

With all the necessary information now being assigned to the new VolunteerVO and sent to the DBService
in PHP, you’re ready to handle the result of the saveVol() method.

private function onVolSaved():void {
    Alert.show("Volunteer saved","OK");
    sendEmail();
}

The first thing that happens here is that the user is shown an alert. The first string, Volunteer
saved, is shown as the alert message, and OK is the alert’s title. Continuing your chain of
functions, the sendEmail() function is called. You’ll use this function in almost the same way
as the onValidateResult() function that assembled a new VolunteerVO object. This time, you create a
new EmailVO object:

private function sendEmail():void {
    var email:EmailVO = new EmailVO();
    email.from = "noreply@flexandair.com";
    email.subject = "New Volunteer Signup";
    email.recipient = "richard@fakemail.com";
    email.body = vol.f_name + ' ' + vol.l_name + " has just signed up as a new volunteer!  " + vol.f_name + " is available " + vol.hpw + " hours per week on " + vol.avail_days + ".";
    emailService.sendEmail(email);
}

This function is simple—essentially just setting the e-mail properties and assembling a message
string for the body of the e-mail message. Obviously, you’ll want to change the e-mail address
to one you can use for testing. ActionScript uses plus signs (+) to concatenate strings, and the
dynamic information is populated from the VolunteerVO object. The new EmailVO is then sent to the
remote object emailService (the MXML ID corresponding to the EmailService class in PHP), destined for
the sendEmail() method. When a result comes back from this call, you’ll handle it with the
onEmailSent() function:

private function onEmailSent():void {
    Alert.show("email sent","OK");
}

This function displays an alert box to let you know the response was echoed back after the remote
sendEmail() method finished.

One more function referenced earlier remains to be written: the onFault() function. If there is a
problem communicating with Zend_Amf, you need to know about it. You’ll use an alert again:

private function onFault(event:FaultEvent):void {
    Alert.show(event.fault.faultDetail + " Fault Code: " + event.fault.faultCode, event.fault.faultString);
}

The FaultEvent is passed in as the variable event. The event has a property called fault, which
contains several pieces of information to help you figure out what went wrong: faultDetail, faultCode,
and faultString, among others. These are displayed in the alert box.

Finally, you need to call the captchaService’s generate() method when the application first
loads so that the image appears. To do this, go to line 2, inside the <mx:Application> tag. Add
this to the properties inside the tag, after layout="vertical":

applicationComplete="captchaService.generate()"

Now, the captchaService.generate() remote method will be called when the application loads. Click the
green Run button, and the application launches in your web browser. You should see something similar
to Figure 12.

Figure 12. The finished form

Complete the form, then click Submit. You should get two alerts in quick succession. Figure 13 shows
this result.

Figure 13. Submission result

Also, check the e-mail at the address you specified in the sendEmail() function. Figure 14 shows the
notification e-mail message.

Figure 14. The notification e-mail message

Troubleshooting

If you get compiler errors in Flex Builder, look in the bottom pane on the Problems tab. Any issues
with the MXML or ActionScript will be displayed here with a line number and a short description.

You might get a “BadVersion” or “DeliveryInDoubt” message if there is an issue
with your PHP calls. Double-check the PHP code for common errors like closing tags and line endings,
and make sure all your classes match their file names. Also ensure that each of your services are
going into $server->setClass() in your gateway.php file.

If your Captcha image is not showing up in the Flex client, check the /captcha folder you created to
hold the generated images. If the folder is empty, it may be that the permissions are blocking your
web server from saving the images there. Make sure it is writable. Another possibility is that the
CaptchaService class can’t find your font. Make sure you place a TrueType (.ttf) font in the
folder you specified in CaptchaService.php. I used the /Vols/include folder in the example.

If the captcha folder contains images, make sure the onCaptchaGenerated() function in ActionScript is
pointing to the right URL. If you followed this article verbatim, the URL is:

"http://localhost/Vols/captcha/" + sessionID + ".png"; 

Next Steps

When you have your gateway.php file set up properly, you can take advantage of most Zend Framework
extensions or any PHP code, for that matter. For a full list of Zend Framework components, go to the
Zend Framework Documentation site.

Another great resource for Flex and PHP development is the Adobe Developer
Connection’s Flex and PHP site. There, you’ll find lots of
information on developing with Flex and PHP—from streamlining your
workflow to useful tips and real-world examples.

Download all the code used in this article.