Using Flex 4 Clients with the PHP Zend Framework Server

The instantiation of the ZFMail.php class establishes the ZF Zend_Mail component at lines 14 and 15. The EmployeeService.php services class then calls the sendMail method in theZFMail.php class passing into the method and object with all the email send parameters and message content. Lines 21 through 26 format and send the email. Line 24 calls the genMail method to format the HTML text for the email body. PHP DOM is used to generate the HTML. How PHP DOM performs the message body HTML tags and content generation is beyond the scope of this article. You can do this just as well with some simple use of HTML tags. If this is a bit much, then just send a plain text message.

How I Test My PHP services Classes

The EmployeeServiceTest.php file, also located in the services folder, is neither a services not PHP object file. Instead this is a file I used to test the operation of the EmployeeService.php services class by running this PHP script from the PHP command line (the PHP CLI scripting engine). I typically test one object method call at a time by un-commenting one of the respective tests contained in this test suite. I run one or more of these test suites anytime changes have been made to one or more methods in the EmployeeService.php services class file.

The EmployeeServiceTest.php file first instantiates the EmployeeService.php services class into an object. Then calls a method within the object, typically passing in a test parameter.

When using the EmployeeServiceTest.php file there is a very important configuration step you need to take when instantiating the EmployeeService.php services class for testing purposes. The normal client-to-sever messaging operation is:

• FlexZF client makes a RemoteObject AMF 3 message call to the PHP Web application server.
• The gateway.php PHP script is called in the PHP Web application server.
• The gateway.php PHP script loads the ZF Zend_Loader and also calls the ZF Zend_Amf component.
• The ZF Zend_Amf component instantiates the EmployeeService.php services class into an object and calls the FlexZF client requested EmployeeService.php object method.
• Database I/O (and other) work is done and a (typically data) result is returned to the FlexZF Flex 4 client for data display update.

Bad news . . . the above steps 1 though 5 never occur when instantiating the EmployeeService.php services class from the EmployeeServiceTest.php file. And the operation depends on the EmployeeService.php services class and requires the ZF Zend_Loader to be present for stand-alone testing. The “how to” instructions are in lines 7, 8, and 9 of the EmployeeService.php services class file.

Well, the good news is that there is a solution. I created a ZF Zend_Loader bootstrap loader file for stand-alone testing of PHP service objects that need to load and use ZF component classes for their basic operations. The name of the file is zendLibarary.php and it is located in the root of the FlexZF Web server root. And all you need to do is include this file when you run the EmployeeService.php services in a test stand-alone environment.

Caveat emptor, be sure to again comment out the line 9 include when you’re through running stand-alone tests. Otherwise Flex 4 client to PHP Web application server messaging will not work and it may drive you crazy as to why things are not working when the Flex 4 client refuses to render Employee data in the panel’s DataGrid.

This little tidbit tip alone my be worth this entire InsideRIA blog article in that you have a convenient and easy way to run, review, and evaluate the operation of ZF component classes in a convenient stand-alone way.

FlexZF Flex 4 Client Example Code Discussion

The FlexZF Flex 4 client install procedure is done in four distinct phases. I did this so that you can examine and review that code at the end of each phase. The four install phases are numbered 0 though 3. Each phase consists of one or more install steps. You should return here as you complete each of the FlexZF Flex 4 client install phases for a code review analysis of the code installed during that phase.

The key phase is the second phase, phase 1 where you use the Flash Builder 4 Data / Services tool in order to auto-generate the AMF 4 RemoteObject messaging between the client and server. Phase 1 install is based on the ADOBE® FLEX® 4 Tutorials document, specifically the chapters:

• Chapter 2: Installing the Flash Builder tutorial database, page 14
• Chapter 4: Creating PHP services for client applications, page 22
• Chapter 5: Manage the access of data through paging, page 31
• Chapter 6: Using data management to synchronize server updates, page 45

Alternately, the above information can also be found in two other resources:

1. Adobe Flash Builder 4 online help
2. Adobe Community Help, click on the [Fb] button.

In either of the above documentation resources, navigate to:
Adobe Flash Builder 4

• Tutorial on data access with Flash Builder 4:
1. Installing the Flash Builder tutorial database
2. Creating PHP services for client applications
3. Manage the access of data through paging
4. Using data management to synchronize server updates

Phase 0: Step 1. Import Flash Builder 4 Project

This base install phase had you import the FlexZF Flex 4 project into your Flash Builder 4 IDE.

Code-wise there is not much to discuss here other than to say the starting index.mxml code is just a bit more than you would see by establishing an initial Flash Builder 4 project with an Application server type of PHP. There are, however, three project starting code additions to reduce just a bit of your initial work. These three code additions are:

1. An ActionScript 3 initData method is established for subsequent install phase utilization.
2. A nearly empty Spark Panel layout container is in place so you can start creating a data display during the next Flash Builder 4 install phase.
3. Four buttons are established for future install tasks. The four buttons do not yet have click handlers established.

Figure 5, provides a view of what you will see after running the imported FlexZF Flash Builder 4 project.

Phase 1: Steps 2 thru 5: Connect to Data / Services

You will see the display shown in Figure 6, after completing phase 1, steps 2 through 5 install steps, and running the FlexZF Flex 4 client. The Flex 4 code that was mostly auto-generated by your install steps is discussed following Figure 6.

During this install phase, you performed the following three procedures:

1. Client to server AMF 3 data connection using the Flash Builder 4 Data /Services tool.
2. Established server to client DataGrid paged data rendering
3. Enabled data management to synchronize client to server updates

Flex 4 client install differs here from the two Adobe tutorials on this topic—one for data paging, and the second tutorial on data management—I have combined both of these tutorials into one so that you have data paging combined with data management to synchronize client to server updates.

Following is the phase one install code discussion.

Let's talk about the Flex 4 code that got generated when running the Flash Builder 4 Data/Services tool. First, notice the script section within your index.mxml page. This is the ActionScript 3 code that performs the AMF 3 RemoteObject call to obtain the data from the MySQL `fb_tutorial_db`.`Employee` database table to render this information in the Flex 4 client DataGrid. You set the AMF 3 remote messaging to call the PHP getEmployeesPaged() method on the EmployeeService object to perform the server-side of the DataGrid display.

The AMF 3 RemoteObject calls are performed asynchronously so that the user's experience with the client are not blocked while waiting for the data to arrive from the server to the client via AMF 3 formatted messaging. Flex 4 uses a CallResponder declaration to eliminate remote messaging blocking and waiting. You can view this CallResponder declaration on line 29 in your index.mxml code module. Think of the CallResponder as a storage point location for received data. In a sense, the CallResponder is the AMF 3 asynchronous messaging broker.

A token is passed to the CallResponder during the client-to-server remote message startup--the action is the DataGrid creation complete. ("Hey, I’m ready to render some data in my DataGrid.") The actual AMF 3 remoting call is made at line 21 to the PHP method employeeService.getEmployessPaged(). And the left-hand assignment of this remoting message call is assigned to the getEmployeesPagedResult.token CallResponder, which was auto-defined for you at line 29 of index.php. The CallResponder listener, which is located within the DataGrid, at line 37, is "{getEmployeesPagedResult.lastResult}". Summarily, when the data is from the server's database arrives at the CallResponder's token, where the DataGrid is listening for the "lastResult". Then when the data is received it is rendered in the DataGrid. The order of AMF 3 remote messaging is:

1. dg_creationCompleteHandler() is registered as the handler for the DataGrid's creationComplete event.
2. The DataGrid's createComplete event is fired and the dg_creationCompleteHandler() method is called
3. The employeeService.getEmployeesPaged() method is called which returns a token (we'll see this code in a bit)
4. The asynchronous call to employeeService.getEmployeesPaged() completes and the DataGrid is updated to the Employee data stream via the CallResponder getEmployeesPagedResult.lastResult, which is the property that contains the last remoting service call result.

One last thought here. And that is where is the employeeService.getEmployeesPaged() ActionScript 3 code and how did it get created? This code was auto-generated when you performed the Flash Builder 4 Data/Services operation. The code is linked in via an XML namespace as an attribute at the top <s:Application XML tag, specifically the XML attribute: xmlns:employeeservice="services.employeeservice.*"

If you look in the Flash Builder's src folder you will find a 'services.employeeservice' folder. This is accessed by the above 'employeeservice' namespace. Line 340 of the '_Super_EmployeeService.as' file, that contains the following code:

/**
   * This method is a generated wrapper used to call the 'getEmployeesPaged' operation. It returns an mx.rpc.AsyncToken whose 
   * result property will be populated with the result of the operation when the server response is received. 
   * To use this result from MXML code, define a CallResponder component and assign its token property to this method's return value. 
   * You can then bind to CallResponder.lastResult or listen for the CallResponder.result or fault events.
   *
   * @see mx.rpc.AsyncToken
   * @see mx.rpc.CallResponder 
   *
   * @return an mx.rpc.AsyncToken whose result property will be populated with the result of the operation when the server response is received.
   */
 public function getEmployeesPaged() : mx.rpc.AsyncToken
 {
     var _internal_operation:mx.rpc.AbstractOperation = _serviceControl.getOperation("getEmployeesPaged");
     var _internal_token:mx.rpc.AsyncToken = _internal_operation.send() ;

     return _internal_token;
 } 

Details of this auto-generated code and how it works are beyond the scope of this article. Note though that there are two Adobe® Flex® 4 Language Reference API references in the comment section of the above code listing (mx.rpc.AsyncToken and mx.rpc.CallResponder), for those who are interested in more details regarding asynchronous remote messaging.

Phase 2: Steps 6 and 7: Generate and code event handlers for the buttons complete

You performed generate and edit in code for event handles for the four buttons, during phase 2, step 6 of the install instructions. This install exercise was following one of Adobe’s tutorial exercises with some code modifications to meet the specific requirements of our article example FlexZF Flex 4 client.

The application view of the phase 2, step 6 exercise, when run, looks identical to the example app run of phase 1. The difference, of course, is that the four buttons now have a click handler method that perform the respective actions of DataGrid data Add, Delete, Revert, and Save All Changes. These buttons are calling methods to perform their defined actions by calling methods in the employeeService class, which was auto-generated during Flash Builder 4 Data/Services tool operation. Again, the details of this auto-generated code and how it works are beyond the scope of this article.

I had you replace your index.mxml with the content of index2.mxml and then run the example, in phase 2, step 7. Suddenly the FlexZF example’s operation noticeably changed. The DataGrid and four-button display panel is the same, however now you have to go through login dialog in order to gain access to the Employee DataGrid display. See Figure 3 for the login example page.

What was added to your example application was authenticated access to the Employee data via a login screen, which uses a MySQL database to hold the authentication credentials (Username and Password).

Next, I’ll review the code added to index.mxml via your cut and paste install operation of phase 2, step 7.

The most significant addition to index.mxml is an mx:ViewStack within the Spark Panel layout container. The first Spark Navigator view is the added login form, encompassing the code from line 124 through line 144. Line 138, the Login button click calls the clickAuthenticate ActionScript 3 method starting at line 94. The login form contains form validation driven from the mxml code at lines 116 and 117. Line 95 checks for validated Username and Password form data before sending it to the server-side EmployeeService PHP class for login authentication, using the MySQL `ft_tutorial_db`.`users` database table data.

The login return status from the server-side EmployeeService PHP class is a Boolean value, true for authenticated, false otherwise. The login result is retuned from the server to the handlerAuthenticateResult event handler method at line 76. The AMF 3RemoteObject return to the event handler was established as follows:

1. Spark CallResponder was established at index.mxml line 111 identifying the handlerAuthenticateResult event handler method as the return callback.
2. Line 100 shows the employeeService.authenticate call to the server result assigned to the authenticateResult.token—which was established at line 111.

Let’s again move back to the handlerAuthenticateResult event handler method at line 76, if the CallResponder authenticateResult.lastResult is returned true (authenticated login) then the code optionally saves to Username and Password off to a Local Shared Object (LS0). Line 90 performs the Spark Panel mx:viewStack change from the login state to the dialog view, as shown earlier in Figure 6.

Just mentioned, in the last paragraph, was that the Username and Password are optionally saved off to a LSO. This action is to make it convenient for the user in the Username and Password are restored to the login dialog at application startup, this saving the effort to recall and restore this information to the login dialog.

The optional saving of this login data is determined by the Remember Password check box in the dialog. Saving the login data is optional for security purposes in that if login is enabled without the requirement of knowing the Username and Password then the user’s access to the Employee data can be gained when the user’s workstation is unmanned.

The FlexZF Flex 4 client’s LSO is partially managed on the application startup method initData at line 22. Line 24 loads the LSO into application memory. If this is a first-time startup, then the initial LSO is established by the AS 3 code in line 26 through 32. Otherwise, the second and all future application logins are loaded into the application, at startup, at lines 33 through 36.

Information on how to use and apply LSO is found in the Flex 4 documentation at the following navigation hierarchy: Home / Using Flex 4 / Application architecture / Security / Writing secure applications / Storing persistent data with the SharedObject class

Phase 3: Step 8: Add record button replaced by and Add form with form validation

The Phase 3, step 8, install instuctions had you cut and paste replace code from the index3.mxml example file into your index.mxml file in your FlexZF Flash Builder 4 project. This install exercise provides an added bonus example. What happens is that the Add (Employee) button is removed and replaced by an Employee Add form. This display change is shown in Figure 8.

A principle reason for a change like this is to validate the new Add Employee user data form input before it is remotely posted to the server-side database. Programming-code-wise, the Add form function addition is fairly straightforward.

First the addButton_clickHandler AS 3 method at line 48 of the phase 2 install is replaced by the same method name, starting at line 59. The new Add form is contained in line 207 though 234. This is a very traditional Flex 4 form, which does not require discussion other than to say the Add button code, at line 231, has a click handler to call the addButton_clickHandler ActionScript 3 method.

The Add form input data is validated by the Flex 4 mxml code in lines 155 through 158. Each Add form text input is checked for valid or invalid date and sets the respective boolean properties at lines 23 through 26.