Flex 4 / PHP Data-Centric Solutions

Perhaps you have gained a few years of experience developing Adobe Flex build RIAs (Rich Internet Applications) integrated with various families of remote Web application servers to meet your data services repository needs.

Flash Builder provides server-side remoting technology supporting ASP.Net, J2EE, HTTP/REST and SOAP Web services, PHP, BlazeDS, ColdFusion, and LiveCycle Data Services for streaming data to and from a Flex 4 client. This article exclusively covers the PHP server-side remoting technology principally with Zend's PHP Zend Framework web application server. New RIA client and PHP sever development opportunities are emerging using the newly released Flash Builder 4 (Flex 4). IDE linked the recent additions to the Zend Framework PHP Web application server for messaging via Adobe Message Format 3 (AMF 3) serial data streams.

Flash Builder 4 provides excellent client-side data management and paging features that bring efficiency to large data set handling. Additionally, the Flash Builder 4 speedy two-way data binding dramatically simplifies database updates without extra coding. This is a nice touch for a common task, but you also need to know to manually perform data-centric binding when it is required.

This article is about providing RIA access to data-centric services using RemoteObject components. It’s not about data-centric remoting services using HTTPService components or WebService components. You can access RemoteObject components with PHP objects in conjunction with third-party software, such as the open source projects AMFPHP and SabreAMF, and Midnight Coders WebORB. This article will exclusively use a fourth open source PHP Web application server environment, which is Zend's Zend Framework. The Zend Framework remote connectivity is now an integral part of the Flash Builder 4 IDE where client/server linkages will be approached in a more consistent manner with a couple of common sets of server-side remoting code. I will demonstrate how easy it is to take advantage of the Zend Framework on the server side.

I chose to write this article to provide a refined and simple data-centric client/server remoting solutions so that you have simple and straightforward methods you fully understand and can apply in a brief instant. You should leave this article with an understanding of two very important RIA data-centric client/server concepts. This article will:

1. Provide you with a convenient and easy way to deploy RIA client/server shared PHP Web application server environment using Zend's Zend Framework.


2. Show you that by mastery and awareness of just a few basic remoting details, the RIA client's data-centric connection to the PHP Web application server is not that difficult to achieve, using either a Flex 3 or Flex 4 development environments.

Flash Builder tools can assist you in creating applications that access data services. You start by creating a Flex project for your applications. You can then connect to a remote data service, configure the access of data from the service, and build a user interface for an application. In some cases, you first create the user interface and then access the data service. These "best approaches" is what this article is all about, specifically using Flash Builder 4, Flex 4 SDK (Flex 4), and remoting with a Zend Framework PHP application server. To get going using Flex 4, I will briefly start with Flex Builder 3, Flex 3 SDK (Flex 3), as migration basis to Flex 4 development.

First I will start with the deployment of a shared Zend Framework PHP Web application server that can serve for either as a Flex 3 or Flex 4 client development or production server. This shared Zend Framework exercise will be followed with three separate Flex 3 and Flex 4 client examples clearly showing how easy data-centric development can be if you have all the required "how to" answers.

In summary, if you do not care deploy the Flex 3 and 4 data-centric examples and instead just review the code, then:

1. First, review the Implementation section.


2. Download the install code and grab the Flex example files from the Flex 3 & 4 Projects folder—see the Requirements section for example code download details.


3. Navigate to the section Flex Client Examples Deployments to follow the code description while viewing the Flex 3 & 4 Projects folder source code.

Encouraged Reading

It’s too much to cover all of the total details per developing Flex 4 / PHP Data-Centric Solutions in this article. Accordingly, my following discussions about the developed code and client to server deployment purposely cut short some implementation details. Before going too far into my article, I suggest that you read the following Adobe Flex 4 documentation:

Differences between Flex 3 and Flex 4 (article)

The Adobe Flex 4 release is a major change from Flex 3. Flex 4 introduces a new component and skinning architecture. You’ll need to know about the new Spark component and skinning architecture when you review my three article examples. As a Flex 3 developer, however, you will likely not encounter too many challenges when compiling Flex 3 applications with Flex 4, since a goal of the new release is to maintain backwards compatibility with Flex 3.

This article provides a general overview of the main objectives in Flex 4, architecture differences, and an introduction to changes in components, layouts, use of states, and effects. The article also answers some questions regarding what to expect when you compile your Flex 3 application in Flex 4. This article does not cover all of the new features and functionality in Flex 4. For that information, read the next article: What's new in Flex 4.

What's new in Flex 4 (article)

A new feature of Flex 3 is the skinning and component architecture, named Spark. Building on top of the existing MX architecture, Spark provides a much more expressive mechanism for developers and designers to work together on the appearance of their Flex applications. Spark currently includes approximately 30 new components and primitives, forming the foundation of Adobe's next-generation components and shown in the three article Flex 3 / Flex 4 article examples.

Developer Connection: Learn Flex and PHP (tutorials)

Adobe and Zend are collaborating to make it easy for PHP developers to create rich Internet apps using Flex and the Zend product suite, which provides a platform for supporting the entire Flex and PHP app lifecycle.

• Article: Why choose Flex and PHP
• Article: The architecture of Flex and PHP apps

Tutorials on data access with Flash Builder / Flex Tutorials) (tutorials)

• Import a service and bind data to application components
• Installing the Flash Builder tutorial database
• Creating ColdFusion services for client applications
• Creating PHP services for client applications
• Manage the access of data through paging
• Using data management to synchronize server updates

Some of my following discussions in this article will not make total sense without an awareness of the concepts contained in the above six topic chapters. Pay particular attention to the above Creating PHP services for client applications chapter.

And I do not deal, in this article, with the details of using Flash Builder 4 as a development tool, so you need to dig into the following documentation too.

Adobe Flash Builder 4 / Using Flash Builder 4 (documentation)

• About Flash Builder
• Flash Builder Workbench
• Working with projects
• Code Editing in Flash Builder
• Creating Custom MXML Components
• Developing AIR applications with Flash Builder
• Debugging, testing, and monitoring applications
• Profiling Flex applications
• Building a user interface with Flash Builder
• Working with data in Flash Builder
• Customizing Flash Builder

Requirements

Adobe Flash Builder 4—formerly Flex Builder 3 (includes the Flex 4 SDK)
Eclipse-based development environment for Flex. Supports visual and code-centric development, code hinting, visual debugging, and so forth. Includes the Flex 4 SDK and Flash Player 10

• Try - 60 days
• Buy
• Note: This article’s RIA solution is also buildable using Adobe Flex Builder 3.x

Alternately: Free Flex 4 SDK
The Flex SDK is the foundation of Flex, providing the core Flex compilers, component library and debugger. Using only the free SDK and an IDE of your choice, you can build and deploy rich Flex applications. Learn more about the Flex Open Source project.

• Download

PHP (both workstation and production server deployment required)

• PHP 5.x Scripting Engine

Web Server (both workstation and production server deployment required)

• Apache HTTP Server
• Alternately Microsoft IIS Web server (preinstalled with Windows XP or 7 Pro)

MySQL Relational database server (both workstation and production server deployment required)

• MySQL Community Server Downloads (5.x)

Zend Framework (Either Full or Minimal download will meet your needs)

• Zend Framework—Latest Release of ZF

Web Debugging Proxy (Optional tools. Tool use is highly recommended) (*)

• Charles
• ServiceCapture
• (*) Adobe Flash Builder 4 provides a built-in Network Monitor tool. For details see Adobe Flash Builder 4 / Using Flash Builder 4 / Debugging, testing, and monitoring

Example files

• Flex 4 - PHP Data-Centric Solutions.zip (ZIP, 116 KB)

Implementation

This article provides you with code examples for PHP server RIA development whether it is migrating Flex 3 development to Flex 4, or just starting out with Flex 4 development using Flash Builder 4. You will have a deployed and fully working (Flex 3 or Flex 4) RIA client development environment integrated with a shared Zend Framework PHP Web application server. This server is capable of use for either workstation or full production Web server use.

The Zend Framework is a shared Web application, which is ideal when working on several RIA client developer workstation projects. On your production Web server the shared Zend Framework PHP server provides a manageable solution for hosting multiple Web sites via virtual hosting or multiple sub-domains from a base domain. Establishing a shared server is not well documented, but most simple to deploy when you know how.

The server is simultaneously shared for Flex 3 and/or Flex 4 Flex/Flash Builder RIA development. Server deploys once and used for any or all RIA client development and ultimate production release.

The article provides three separate and unique Flex client examples each using the identical server-side PHP service calls and sharing of the database repository records. Each Flex client example identifies and shows different ways that you can perform data-centric remoting to the identical server-side functionality. I also explain when and why you use the alternative remoting scenarios.

Following later are three sets of detailed step-by-step instructions to create client/server remoting connections both using manual remoting code generation plus the new auto-generated data-centric access provided the Flash Builder 4 data services. The three Flex client examples are:

• ContactFx3: A Flex Builder 3 project that uses manual code generation for Remote Object AMF 3 remoting to the Zend Framework PHP Web application server.


• ContactFx4: A Flash Builder 4 project that uses manual code generation for RemoteObject AMF 3 remoting to the Zend Framework PHP Web application server. This project is provided to show the difference in Flex 3 vs. Flex 4 client application code. (The data-centric remoting code is essentially the same between the ContactFx3 and ContactFx4 Flex client examples.)


• ContactFx4CDS: A Flash Builder 4 project that provides an auto-generated connection RemoteObject AMF 3 remoting to the Zend Framework PHP Web application server using Flash Builder 4 “Connect to Data/Services” feature. This feature is new to Flash Builder 4 and not available with the Flex Builder 3 IDE.

What is Not Provided

The subject thrust of this article is about creating Flex applications that can perform client/server data-centric services using RemoteObject components. Details on developing Flash Builder 4 Spark components, skinning of Flash Builder 4 applications, and the desired structure of Flex clients is left to Adobe’s fine developer documentation on these topics to say nothing about the plethora of example code provided by Adobe and the Adobe developer community.

Examples Service: The Contacts PHP Services Class

The three article example applications ContactsFx3, ContactsFx4, and ContactsFx4CDS each contain a services folder, which, in all three examples, contains the same identical Contacts PHP object. This is shown in Figure 1.

How and where to deploy the Contacts PHP services class

The core Web site template folders for the three article example applications ContactsFx3, ContactsFx4, and ContactsFx4CDS are deployed to your Web server root. In your Downloads folder, you will see a Web Site Templates folder. Drag the contents of this folder (not the folder) to your Web server root. See Figure 1 for the view of the deployment of the three-example Contacts applications into your Web server root.

Reviewing the Contacts PHP services class code and operation

I've discussed details of PHP server-side services objects in my three other InsideRIA PHP data-centric articles. You can read these articles for more complete details of how PHP server-side services objects are structured and operate:

• AMF3 PHP Server Objects to Flex Client Object Relational Mapping
• Processing AMF 3 PHP Server Object Arrays on the Flex Client Using Object Relational Mapping
• Photo Gallery Mate Framework, With Photo Cachingg

Minimally, open any one of these three Contacts.php classes to review how it’s structured and review the services provided by each object methods (functions). If you want to observe the operation of the respective Contacts.php methods, there is test code at the bottom of the Contacts.php file. Uncomment PHP code test groups, one at a time, then run using PHP (CLI), like this to view the output results:

$: php -f Contacts.php (enter)
View method output results here.

You’ll learn a lot about the PHP services operations with this PHP script running exercise.

Flex Client Examples Descriptions

This section discusses both manually and auto-generating data-centric remoting connections from Flex 3 and 4 clients to the Zend Framework PHP Web application server. Covered here is not only the “how to” for Flex client side remoting connections, but also when to use both approaches. We’ll actually demonstrate through the example Flex client example code the evolution of Flex data-centric client/sever remoting connection development.

Flex 4 data-centric client /server remoting connections

This article provides three Flex 3 or 4-built client examples, each for specific purposes. My first purpose is comparing functionally identical client-side applications written using Flex Builder 3 and Flash Builder 4. These two are the ContactsFx3 and ContactsFx4 examples respectively.

This pair of examples provides you with some ideas per migrating from Flex 3 to Flex 4 client development. More specifically, these two code examples show you how to manually establish AMF 3 RemoteObject messaging between the Flex 3 or 4 clients and the Zend Framework PHP Web application server. You will learn that Flex 3 and Flex 4 remoting coding are mostly identical, but not 100%. I want to make clear the differences—next in the Flex Client Examples Deployments.

The third, and last, example is ContactsFx4CDS, where I will show you how to automatically generate the AMF 3 RemoteObject messaging between the Flex 4 client and the Zend Framework PHP Web application server. There is a tool in Flash Builder 4—not available in Flex Builder 3—named Connect to Data/Services, hence the reason for the “CDS” suffix on the example’s name.

The details of using the Flash Builder 4 Connect to Data/Services tool are discussed in the next section Flex Client Examples Deployment. First, I need to discuss what the tool provides, and more importantly, when to use auto-generated client to server AMF 3 Remote Object connections.

The Flash Builder 4 Connect to Data/Services tool is good for applications where the client needs a remote connection of any or all of the CRUD (Create, Read, Update, and Delete) client/server data management functions. CRUD management of data management remoting is indeed the core of most RIA client/server solutions—but not all solutions. For example, in my photo gallery RIAs, I certainly use some or all of the CRUD elements. Many times though, I want to provide more user experience functionality such as search for and retrieving photos for client side gallery rendering based on the photo’s metadata.

Your first thought might be to think that if the AMF 3 RemoteObject client/server connection required more than the CRUD elements that you would need to abandon the use of the Flash Builder 4 Connect to Data/Services tool. The answer to this is not necessarily so. There is no reason why you can’t use the Flash Builder 4 Connect to Data/Services tool for your CRUD remoting plus write manual client/server remoting for connection to another PHP services object or additional object methods in your base PHP service.

There are other potential limitations in using the Flash Builder 4 Connect to Data/Services tool to establish your client/server remoting. You may have a need to manually define data-centric remoting object data structures when using micro-architectures such as Cairngorm, Maté, PureMVC, or Swiz. You may be developing your Flex client app using a framework like Swiz, Mate, or Cairngorm where you want to 100% control your client/server message remoting. Sometimes your RIA data in your server’s repository is not available in a CRUD format. Flash Builder 4 Connect to Data/Services tool nominally renders data in a Flex DataGrid control and this does not fit your needs. You should write and deploy AMF 3 RemoteObject code in these situations.

In summary, this is why I provide you with three examples showing Flex 3 and Flex 4, with manual remoting plus a Flex 4 auto-generate remoting example. You need to be aware of all the client/server remote messaging alternatives. My three examples ContactsFx3, ContactsFx4, and ContactsFx4CDS are easy to deploy via Flex 3 and/or 4. Deploy one or all of the examples and learn what happens.

Web Application Server PHP Data Services Layout and Environment

This article section is lengthy because you need to understand and deploy all the RIA server-side system elements. Plus I need to cover all the technical details of what is on the server side and especially how you deploy and share the Zend Framework Web application server. Accordingly, be sure to read this section closely and fully under stand all of the server-side operations and functionality

Server: Why the shared Zend Framework Web application server?

You’ll see how to utilize only one Zend Framework Web application server in this section. In my opinion, this is a very important deployment factor for you to consider.

Let’s discuss the shared server from two perspectives, your workstation development Web server and the production Web server (the publicly released Web site). There’s another benefit from the deployment and update maintenance standpoint. One shared server means that Zend Framework updates are a snap—once on your development workstation and once on the production Web server. Our server site layout architecture is designed such that no Web site specific code resides inside the Zend Framework hierarchy of code.

Zend Framework sharing on your development workstation is ideal and convenient. What this means is that Flash Builder 4 will not attempt to auto-load a new copy of Zend Framework each time you create a new Flash Builder 4 project using the Connect to Data/Services tool.

Maintaining only one copy of the Zend Framework on your production Web server makes the maintenance and upgrade decisions much easier. Deployed and set up correctly, updates can happen in a matter of just a few moments of IT work. Contrast this with a setup for each virtual host Web site or sub-domain Web site containing its own copy of the Zend Framework. Yikes! Where to start and what to do first?

Next I’ll discuss how you should deploy your server’s system elements for a best-use solution.

Server: PHP Framework System Elements and Functional Description

Figure 5 provides a roadmap for reviewing RIA server-side system elements. It also provides us with a road map for how to best deploy your server-side elements.

The server-side elements reside in the root of your Web server, and then are contained within the PHPFrameworks folder. Contained in the PHPFrameworks folder are two sub-folders, WEB-INF and Zend Framework. You will need all of these server-side elements for you workstation Web application server. It is worthy to note that deploying the content of the WEB-INF folder on your production server is optional—mostly for security purposes. If you do use the SiteGenScripts folder on your production server, I do recommend removing them after your production server Web site is deployed and operational.

The WEB-INF folder contains three sub-folders used almost exclusively for development purposes on your workstation.

SightGenScripts

• You will use these scripts each time you create a new server-side Web site to generate the required deployment script files to link your Flex 3 or 4 client-side code to the Zend Framework. Extensive details about the script’s use and application follow in the section Server: Using the PHPFrameworks WEB-INF/SiteGenScripts. First a discussion is required on why these scripts are required (following in the next section).

flex

• These two files are used each time you create a new Flash Builder 4 data-centric project. Each Flash Builder 4 Flex Compiler Property needs to access a copy of the services-config.xml. This is a handy common reference repository, which eliminates the installation of this config file in each and every Flash Builder 4 project. Use details follow in this section.

SQL Schemas

• This folder is simply a convenient location to store the SQL schema files for any or all of your server-side database repositories. These files can be stored in any other convenient location within you workstation development environment.

Server: Installing PHP Framework System Elements

This step is quite easy to perform. If you haven’t already done so, download and unzip the Flex 4 - PHP Data-Centric Solutions.zip file. Copy the PHPFrameworks folder from inside the Downloads folder to the root of your workstation Web server. The same PHPFrameworks folder can also be deployed to your production Web server, if you are so inclined to do this now. That’s all that it takes for deployment.

Next is to install the Zend Framework Web application server. First download and unzip the ZendFramework folder, where the download was indentified in the earlier Requirements section of this article. Next, copy the following files and one folder from the unzipped ZendFramework folder into your Web Server Root/PHPFrameworks/ZendFramework folder, as shown in Figure 5 and following:

• INSTALL.txt file
• LICENSE.txt file
• README.txt file
• library folder

This completes your deployment of your PHP framework system elements.

Linkage of the Flex client and PHP server build

I’ll explain the use of the developer files contained in the server’s WEB-INF folder in the next two sections. First, in this section, I will discuss how all of your Web site files and PHP framework system elements are linked together to work in tandem.

Refer to Figure 6. First, the two dotted line linkages exist only during the Flex client/server development process. These linkages, or for that matter, Flex or Flash Builder IDE system elements, do not exist on your production Web server.

The ~/PHPFrameworks/WEB-INF/flex/services-config.xml file, residing in the Web server root, provides the project build linkage information. Details about how Flex 3 or Flex 4 client build linkages to the PHP server are configured and used follow in the section titled Flex Client Examples Deployments.

Contained in your Flex 3 or 4 built Web site folders is a file named gateway.php. This file provides the linkage from your Web site’s generated Flash file to your PHPFrameworks/Zend Framework Web app server. We need the PHP Zend Framework for just one requirement—that is to provide Adobe Action Message Format — AMF 3 message data serialization and deserialization between the Flex client and our data-centric Web application server.

There are many other APIs contained in the Zend Framework Web application server that you can take advantage of. You might want to visit the Zend Framework Programmers Reference Guide. In particular you may want to review the AMF 3 Zend Framework API: Zend_Amf.

Server: Using the PHP Framework WEB-INF/flex files

The Web server’s ~/PHPFrameworks/WEB-INF/flex folder contains two files:

1. Flex - Additional compiler arguments.txt
2. services-config.xml

File 1 is installed within your Flex or Flash builder project Properties settings to provide a link from your project to file 2, services-config.xml. You could alternately store yours in some other convenient workstation location.

Each PHP data-centric Flex or Flash builder project needs to know the location your services-config.xml file. This is where the Flex - Additional compiler arguments.txt file comes into play with Flex or Flash Builder client development. Refer to Figure 6, above and note that there is a linkage between Flex or Flash Builder IDE and the services-config.xml file located in the Web server flex folder. Your Flex or Flash Builder Flex compiler requires the information in order to build the linkage between your client/server data-centric solution.

You cut and then paste the contents of the Flex - Additional compiler arguments.txt into your Flex or Flash Builder IDE => Properties => Flex Compiler => Additional Compiler Arguments—for each new project—so that your Flex Complier can compile and build a working client server solution.

Now that your Flex or Flash Builder build is linked (points to) the to the services-config.xml file, I can talk about the purpose for this config file. Again, keep in mind that you only need this file of the Web site client/server application build. Once your site is built and deployed to your production server the linkage to the services-config.xml file is no longer required.

The services-config.xml file contains two sets of build environment parameters, a service definition and a channel definition. If you view the services-config.xml file you will note that the service (a class of “flex.messaging.services.RemotingService”) has an id=“ZendAMF” containing a channel ref=“zend-endpoint”. In turn, the channel-definition has an id=“zend-endpoint” (the linkage parameter from the service) that gives us the endpoint of uri=“gateway.php”, a file with a class of “flex.messaging.endpoints.AMFEndpoint”.

Said another simpler way, your Flex or Flash Builder generated application SWF file has a “ZendAMF” linkage to the server-side Zend Framework via the “gateway.php” file. At application startup your application SWF will call the “gateway.php” file to create a connection to the in the Zend Framework’s “Zend-Amf” API for AMF 3 message serialization and deserialization. See Figure 6 for a view of the “gateway.php” connection to the Zend Framework.

By now you might be sensing that some details are missing per the connection of the Web site SWF file to the server-side Zend Framework via the “gateway.php” file. Like, “all right where is the magic?” The answer is the PHP code inside the “gateway.php”” file, which I will discuss in the next section.

Note that the contents of the services-config.xml file remain constant for all Flex or Flash Builder projects that you create on your development workstation.

Server: Using the PHPFrameworks WEB-INF/SiteGenScripts

Each Flex or Flash Builder deployment requires two files in client /server Web server root. These files, which provide the data-centric solution, are:

1. amf_config.ini
2. gateway.php

The amf_config.ini file contains four configuration parameters:

1. webroot = absolute data path to your Web server root.
2. zend_path = absolute data path to your ZendFramework/library folder.
3. amf.production = Boolean, true if Web site is in production mode, false otherwise.
4. amf.directories = folder name where your PHP services files are contained relative to your Web site’s root on the Web server.

The gateway.php file reads the amf_config.ini file at application startup time to pick up the above four ‘.ini’ configuration parameters.

Now, lets discuss when and how you these two files, amf_config.ini and gateway.php, how they are created, and how they are used. Previously I diagramed and discussed the linkage of the Flex 3 or 4 Web site to the Zend Framework using the gateway.php file. We have three example Flex-built Web site scenarios, per how these two files are generated. In each of these example scenarios, you will run PHP script or scripts, using the PHP (CLI) script engine to generate one or both of these two files.

Your next steps will be to learn how to generate these two files. First, though, you need to establish some PHP script parameters that match the data paths of your Workstation’s Web server environment. This step is unique in that you will only need to perform this once for a given workstation environment.

Navigate (change directory) from a command (terminal) window to your Web server root and then to the folder ~/PHPFrameworks/WEB-INF/SiteGenScripts. Then run the ZendPathTest.php script using your PHP (CLI) scripting engine, like this:
$: php -f ZendPathTest.php

The resultant PHP script run output will look similar to the Listing 1 display.

Listing 1: Output from running the ZendPathTest.php PHP script.

Follow the instructions in Listing 1 to edit in this data_path parameter into Gen_amf_config.ini and GenZendAccess.php PHP module files, making these two script files usable for your specific Web site development environment. Again, this will be a one-time only operation, unless you change your Flex client/server development environment.

Copy the specified PHP script to your Web site root and run the PHP script using your PHP (CLI) scripting engine for the following three examples Flex Web site example builds.

Flex Builder 3 project that uses manual remoting code generation

ContactFx3 example: Flex Builder 3 project that uses manual code generation for RemoteObject AMF 3 remoting to the Zend Framework PHP Web application server. This is the only remoting to Zend Framework option when using Flex Builder 3.

1. Copy GenZend.Access.php file to your Web site root.
2. Then navigate (change directory) from a command (terminal) window to your Web site root. Run the GenZend.Access.php script using your PHP (CLI) scripting engine, like this:
   $: php -f GenZend.Access.php
3. This will copy the gateway.php file to your Web site root plus generate a properly configured amf_config.ini in your Web site too.

Flash Builder 4 project that uses optional manual remoting code generation

ContactFx4 example: Flash Builder 4 project that uses optional manual code generation for RemoteObject AMF 3 remoting to the Zend Framework PHP Web application server. (Note the following procedural steps are the same procedural steps per the previous Flex Builder 3 project code generation.)

1. Copy GenZend.Access.php file to your Web site root.
2. Then navigate (change directory) from a command (terminal) window to your Web site root. Run the GenZend.Access.php script using your PHP (CLI) scripting engine, like this:
   $: php -f GenZend.Access.php
3. This will copy the gateway.php file to your Web site root plus generate a properly configured amf_config.ini in your Web site too.

Flash Builder 4 project that provides an auto-generated connection

ContactFx4CDS example: Flash Builder 4 project that provides an auto-generated connection RemoteObject AMF 3 remoting to the Zend Framework PHP Web application server using Flash Builder 4 “Connect to Data/Services” feature. This feature is new to Flash Builder 4 and not available with the Flex Builder 3 IDE.

1. Copy Gen_amf_config.ini.php file to your Web site root.
2. Then navigate (change directory) from a command (terminal) window to your Web site root. Run the GenZend.Access.php script using your PHP (CLI) scripting engine, like this:
   $: php -f Gen_amf_config.ini.php
3. This run PHP script action will only generate a properly configured amf_config.ini in your Web site root and not install a the gateway.php file.
4. Then when you later use Flash Builder 4 PHP Connect to Data/Service tool, the tool will automatically create the gateway.php file in your Web site root.

Examples Repository: Install the Contacts Database

The database schema file, contacts.sql, is contained in your Web server root in the ~/PHPFrameworks/WEB-INF/SQL Schemas folder. See Figure 5 for location view.

Install the Contacts database, database table, and database contents on your MySQL database server using your preferred MySQL database client.

Flex Client Examples Deployments

Refer to the previous three screen shots of the three example applications, Figure 2, Figure 3, and Figure 4 respectively. It this section I will talk about the installation and deployment of these Flex 3 and 4 client examples.

First note in these screen shots that output display is different in each, even though the Flex code is functionally identical in the three examples, ContactsFx3, ContactsFx4, and ContactsFx4CDS. The Flex client application differences are worthy of an explanation.

The ContactsFx3 and ContactsFx4 examples are close to being identical source code wise—with code discussion to follow—the former created using Flex Builder 3 and the latter created with Flash Builder 4. In using Flash Builder 4 you must now “skin” the application before its production release. With the ContactsFx4 example the skinning has not been applied because Flex application skinning is not a topic of this article.

The ContactsFx4CDS example’s Flex client DataGrid display is notably different than either the ContactsFx3 and ContactsFx4 examples. The reason being is that I used the Flex 4 Connect to Data/Services tool to create the connection to the Zend Framework PHP Web application server. In the first two examples I manually wrote the code to create the Flex client DataGrid and Add Contacts input dialog. By using the Flex 4 Connect to Data/Services tool, the DataGrid with Add and Delete Contacts editing capability is generated as part of the tool’s remoting connections operations.

The balance of this article centers on installing, configuring, and building the three Flex 3 or 4 clients using Flex Builder 3 and Flash Builder 4. By now, the PHP server-side of your examples should be installed and configured for communication with the Flex clients. That is if you followed and performed the earlier server-side system element configuration and deployment. Be sure you are ready with the PHP server-side system elements by making sure you have performed the installation and configuration per the following previous topics:

     How and where to deploy the Contacts PHP services class
     Server: Installing PHP Framework System Elements
     Server: Using the PHP Framework WEB-INF/flex files
     Server: Using the PHPFrameworks WEB-INF/SiteGenScripts

The Flex 3 and 4 client example source code is available in your Downloads folder inside of the Flex 3 & 4 Projects folder. The examples source code is available in two formats—with your choice on which format to install into your Flex Builder 3 or Flash Builder 4 projects—as follows:

1. The project’s “src” folder contents where you create the Flex or Flash Builder project and drop in the “src” folder contents into the project.
2. A Flex Builder 3 Import (project_name.zip) file and/or two Flash Builder 4 Import (project_name.fxp) files that you can directly import into Flex Builder 3 or Flash Builder 4 respectively.

Next create any or all the three Flex Builder 3 and/or Flash Builder 4 projects, ContactsFx3, ContactsFx4, and ContactsFx4CDS, and install the respective source code using one of the above two alternatives.

If you need “how to” assistance in creating Flash Builder 4 Flex client projects, the information you need is found here Using Flash Builder 4 => Working with projects:

     About Flash Builder projects
     Creating Flex projects
     Managing projects
     Exporting and importing projects
     Exporting a release version of an application
     Managing project resources

Refer back to Figure 6: Linkage of the Flex client and the PHP server build and the section topic titled Server: Installing PHP Framework System Elements and the sub-section Linkage of the Flex client and PHP server build respectively. This is where I discussed creating your Flex 3 or 4 build linkage to the server-side ~/PHPFrameworks/WEB-INF/flex/services-config.xml file. Recall that you edited the Flex - Additional compiler arguments.txt file contents to contain the absolute data path to the services-config.xml file located in your Web server root to match your workstation development environment.

Now you cut and then paste the contents of the Flex - Additional compiler arguments.txt into your Flex or Flash Builder IDE => Properties => Flex Compiler => Additional Compiler Arguments—for each of the three article example Flex 3 or 4 client build projects—so that your Flex Complier can compile and build a working client/server solution. See Figure 7 for a typical example of the Additional Compiler Arguments parameter. This is a very important build configuration parameter step to get 100% correct. If this parameter is missing or an incorrect data path, then your Flex/PHP application client/server remoting will not operate.

Following are overview code discussions for each of the three article’s examples, ContactsFx3, ContactsFx4, and ContactsFx4CDS. The ContactsFx4CDS example section also provides step-by-step instructions on how to perform the client-to-server AMF 3 RemoteObject using the Flash Builder 4 Connect to Data/Services tool.

In the following three examples, I mostly review the Flex 3 or Flex 4 code associated with the data-centric AMF 3 RemoteObject client/server remoting messaging. How the entire example applications function can be determined using Adobe’s Flex Builder 3 or Flash Builder 4 documentation.

If your desire is to build and review the ContactsFx3 Flex client’s operation, here are the Adobe online documentation references: Adobe Flex 3 Help and Adobe® Flex™ 3.5 Language Reference (Flex 3 version).

If your desire is to build and review the ContactsFx4 or ContactsFx4CDS Flex client’s operation, here are the Adobe online documentation references: Adobe Flex 4 and ActionScript 3.0 Reference for the Adobe Flash Platform.

Example Client 1: ContactsFx3 Flex client with manual connect to Data/Services

Flex Code Overview

Refer to the index.mxml file. The RemoteObject connection is made by lines #141 though #147, with shared fault hander for the five separate PHP services object method calls. The PHP Contacts services object is linked to by the source MXML attribute. Our destination MXML attribute identifies ZendAmf as our services connection linkage referenced by the “additional compiler arguments” property in the services-config.xml—file discussed earlier.

Note that each of the five method call results are handled by a different ActionScript 3 function in the <mx:Script>.... </mx:Script> set of MXML tags. The unique ActionScript 3 functions to handle result returns are required because the data returned by each PHP services method is different and in two PHP services method calls, with the updateContact, and deleteContact remoting calls the return from the PHP Web application server is void (no data). Accordingly each PHP server data return result needs to be handled and processed in a different manner.

I developed the AMF 3 RemoteObject connection to the Zend Framework PHP services object using MXML tag code. The same remoting connection can be coded using ActionScript 3 code. This—commented out—functionally identical remoting code, written in ActionScript 3, is shown in lines #33 through #40. Uncomment these lines to use this code instead and also line #29. Additionally you must comment out the RemoteObject MXML tags at lines #141 to #147 using a pair of MXML comment tags. The requirement is that you cannot have two AMF 3 RemoteObject Flex 3 or 4 calls with the same name, i.e. contactsRemote.

The ContactVO ActionScript 3 class (inside the valueObjects folder) describes the contact “value object” data returned from the contacts MySQL database via the Zend Framework PHP Web application server. The nominal return of ContactVO object is as an array of ContactVO objects via the getContacts PHP services object method call. Just one ContactVO object is returned to the client when the getContactsByContactNo PHP services object method is called.

Example Client 2: ContactsFx4 Flex client with manual connect to Data/Services

Flex Code Overview

The ContactsFx4 Flex client in the index.mxml file is functionally and logically identical to the code in the ContactsFx3 Flex client in the to the index.mxml file. Accordingly, there is no need to again provide the same code overview here. There are some differences in the code structure and syntax between Flex 3 and Flex 3 built projects. I took my working ContactsFx3 project and manually converted it to ContactsFx4 Flex 4 so you can see the subtle differences between the Flex 3 and Flex 4 coding. Hopefully, this example provides starting ideas for when you migrate some of your projects from Flex 3 to Flex 4.

First, you can easily find the five the components that have been updated, from Flex 3 (ContactsFx3 example), to Flex 4 Spark component and skinning architecture in the ContactsFx4 example. These Spark components use an “s” namespace in the xml tags, like this <s:someComponent…..> Note also the Spark “s” namespace XML attribute in the starting <s:Application ……> tag, as follows:
   xmlns:s="library://ns.adobe.com/flex/spark"

Second, Flex 4 projects required a Spark component set of layout parameters. This Spark component is shown in lines #11 to #13 in the ContactsFx4 index.mxml file where the layout of the application is defined as a Spark VerticalLayout.

And last, the AMF 3 RemoteObject MX connection in ContactsFx3 Flex index.mxml is converted to a Spark component, as show in lines #160 to #166 of the ContactsFx4 index.mxml file. Note also that the RemoteObject Spark component and the MX contact input form valuators are enclosed in a pair of <fx:Declarations>....</fx:Declarations> tags. The declarations tags are by Flex 4 convention. The “fx” namespace XML attribute is also defined in the starting <s:Application ……> tag, as follows:
   xmlns:fx="http://ns.adobe.com/mxml/2009"

Again, I’ll state that the ContactsFx3 and ContactsFx4 index.mxml example code is functionally identical. Where they differ slightly is in the code syntax as described in the preceding three paragraphs. I hope that this helps with your potential Flex 3 to Flex 4 build project migration updates.

Example Client 3: ContactsFx4CDS Flex client with auto-generated “Connect to Data/Services”

Flex Code Overview

The Flex 4 ContactsFx4CDS index.mxml AMF 3 remoting code noticeably diverges from the code we just discussed for the ContactsFx3 and ContactsFx4 index.mxml Flex code examples. The reason for the ContactsFx4CDS code divergence is that the AMF 3 client to PHP application server code is auto-generated by the Flash Builder 4 Connect to Data/Services tool.

You will establish the auto-generated remoting connection by performing the steps outlined in the next section titled Using Flash Builder 4 Connect to Data/Services tool for client/server remoting. I thought it best to first discuss the Flex client code so you know what to expect and as an in-line comparison with the two manual remoting code examples.

For now, I will assume that you have performed the Flash Builder 4 Connect to Data/Services steps below for my review of the Flex 4 client code. You can always return here for the code discussion after you run the Flash Builder 4 Connect to Data/Services tool.

In this example, I created an application that contains an editable DataGrid that displays employee records. You can modify one or more records in place in the DataGrid. You can also add or delete selected records from the DataGrid. All the changes in the DataGrid are local until you select a Save All Changes button that updates the database. This is application behavior that is much richer the previous two Flex client code examples with manually written AMF 3 RemoteObject remoting connections.

I will assume from here that you have established your Zend Framework PHP application server and have a Web site in your Web server root—nominally a folder when performing development on you workstation. And included in your Web site is a services folder containing a working contacts.php PHP service. In other words, from previous exercises in this article, the server-side elements are working and ready to use.

You perform five major development steps, when you build Flex 4 data-centric RIA solution from scratch, using the Flex Builder 4 Connect to Data/Services tool. These major steps, in order, are:

1. Create an empty Flex 4 project using the Flex Builder IDE
2. Create the Remote Service using Flash Builder Data/Services
3. Enable Data Management Features
4. Create the application and add a DataGrid and Buttons
5. Generate the code and event handlers for the Buttons

My ContactsFx4CDS index.mxml example code will eliminate you performing steps #4 and #5 because I provide this code within my index.mxml example code. Create your Flex 4 project using the Flex Builder IDE. In the Create a Flex Project dialog window set the Main application file: name to index.mxml. Install the contents of my index.mxml example code file into your Flex 4 project ~/src/(default package)/index.mxml file.

Now you have a Flex 4 project with just one code file at ~/src/(default package)/index.mxml. Next I will discuss the code generated by the Connect to Data/Services tool. Your choice is to move forward and perform the two steps: Create the Remote Service using Flash Builder Data/Services and Enable Data Management Features, or follow on here to obtain an expectation of what the code auto-generation exercise will produce.

Generated Flex Code Differences from manual connect to Data/Services

You will note two new folders in your Flex 4 project ~/src folder after running the Connect to Data/Services tool, defined below in step groups #1 and #2 below. The respective folder names are services.contacts and valueObjects. The services.contacts folder contains two ActionScript 3 class files: _Super_Contacts.as and Contacts.as. The value Objects folder contains three ActionScript 3 class files: _ContactVOEntityMetadata.as, _Super_ContactVO.as, and ContactVO.as. The summary of the ActionScript 3 code files—excised from the generated ActionScript 3 class files headings—follows (note that some class files are meant to be extensible, while some class files do not allow modification):

• ~/src/Services.contacts/_Super_Contacts.as
This is a generated class and is not intended for modification. To customize behavior of this service wrapper you may modify the generated sub-class of this class—Contacts.as.
• ~/src/services.contacts/Contacts.as
This is a generated sub-class of _Contacts.as and is intended for behavior customization. This class is only generated when there is no file already present at its target location. Thus custom behavior that you add here will survive regeneration of the super-class.
• ~/src/valueObjects/ContactVOEntityMetadata.as
This is a generated class and is not intended for modification.
• ~/src/valueObjects/Super_ContactVO.as
This is a generated class and is not intended for modification. To customize behavior of this value object you may modify the generated sub-class of this class—ContactVO.as.
• ~/src/valueObjects/ContactVO.as
This is a generated sub-class of _ContactVO.as and is intended for behavior customization.This class is only generated when there is no file already present at its target location. Thus custom behavior that you add here will survive regeneration of the super-class.

This Flash Builder 4 auto-generated Flex code is fairly elegant stuff. Some of the code is marked as DO NOT MODIFY (otherwise your remoting connection will fail). A good share of the auto-generated Flex 4 code contains comments for the ActionScript 3 functions. A detailed analysis for these five generated Flex 4 ActionScript 3 code files: _Super_Contacts, Contacts, _ContactVOEntityMetadata, _Super_ContactVO, and ContactVO and code module extensible modification are beyond the scope of this article.

There is one interesting auto-generated code note worthy of discussion. Earlier I mentioned that all the changes in the DataGrid are local until you select a Save All Changes button that updates the remote database via the Zend Framework PHP application server. The code that performs this edit caching and then remote posting is in the _Super_Contacts.as class. If you are the code curious type, then what is going on is worth a look. Read the code comments associated with each method (function) in the _Super_Contacts.as class. It’s nice that this code is auto-generated for you.

Using Flash Builder 4 Connect to Data/Services tool for client / server remoting

You typically perform four sets of procedure steps using the Connect to Data/Services tool (assuming you have already created a Flex 4 project):

1. Create the Remote Service using Flash Builder Data/Services
2. Enable Data Management Features
3. Create the application and add a DataGrid and Buttons
4. Generate the code and event handlers for the Buttons

For our example the last two sets of procedure steps are not performed because my example code provides this code prebuilt. “How to” references are provided at the end of this section on how to perform these steps for your future Flex/PHP Data-Centric Solutions.

Create the Remote Service using Flash Builder Data/Services

1. From the Flash Builder Data/Services window tab, select Connect to Data/Service. Select PHP. Click Next.


2. Click Browse and navigate to your ContactsFx4CDS Flex 4 project’s server-side ~/Webroot/ContactsFx4CDS/services/Contacts.php file, which you deployed earlier. Select Contacts.php. Click Finish.


3. In the Flash Builder Data/Services view, from the context menu for the getContacts() operation, right-click and select Configure Return Type.


4. Flash Builder requires a custom data type for data returned from the data service. By introspecting the PHP services object method getContacts() operation, you can auto-define the custom data type return.


5. In the Configure Return Type dialog, Auto-Detect the Return Type is selected by default. Click Next.
   


6. Flex uses custom data types to access and update complex data types returned from the server. The getContacts() object method returns an array of the fields of records from the Contacts table in the database. The Configure Return Type dialog displays the properties of the data type returned by the service as an Array of ContactVO. Click Finish to configure array of ContactVO as the return type.



7. Right-click on addContact() and select Configure Input Type. For the contactVO Parameter, set Select Type to ContactVO and click the OK button.



8. Right-click on addContact() object method and select Configure Return Types. Select the Use an existing data type button, and select ContactVO from the Menu, and then click the Finish button.



9. Right-click on deleteContact() object method and select Configure Input Types. For the contactNumber Parameter, set Select Type to “int” and click OK.


10. Right-click on deleteContact() object method and select Configure Return Type. Select the Use an existing data type button, and select “void” from the Menu, and then click the Finish button.


11. Right-click on getContactByContactNo() object method and select Configure Input Types. For the contactNumber Parameter, set Select Type to “int” and click OK.


12. Right-click on getContactByContactNo() object method and select Configure Return Type. Select the Use an existing data type button, and select ContactVO from the Menu, and then click the Finish button.


13. Right-click on updateContact() object method and select Configure Input Types. For the contactNumber Parameter, set Select Type to “ContactVO” and click OK.


14. Right-click on updateContact() object method and select Configure Return Types. Select the Use an existing data type button, and select “void” from the Menu, and then click the Finish button.

Enable Data Management

1. In the Data/Services view, expand the Data Types node and select the ContactVO data type.


2. From the context menu for theContactVO data type, select Enable Data Management. View full size graphic.


3. In the Select Identity Properties dialog, check contactNumber. Click theNext button.



4. In the Map Database Operations dialog, specify the following operations:
   • Create (Add) Operation: addContact ()
   • Get Item Operation: getContactByContactNo ()
   • Update Operation: updateContact ()
   • Delete Operation: deleteContact ()



5. Click Finish. Data management is now enabled for this operation. Flash Builder 4 generates client code that can update data using a combination of the mapped operations.


6. Your Data/Services tab window will appear configured like this figure:

The following two sets of procedure steps are not required, for may example, because the ContactsFx4CDS example Flex 4 client application provided this code pre-built as part of the article’s example in order to save you some effort getting going with a first—or very early—working PHP remoting solution. You do need to know how my ContactsFx4CDS example code was created, per the steps below, for you future development needs. The following two sets of development procedure steps, required for every Flash Builder 4 Connect to Data/Services tool Flex 4 client:

    Create the application and add a DataGrid and Buttons
and
    Generate and code event handlers for the Buttons
can be found here in the Adobe documentation: Adobe Flex 4 then navigate to:
Tutorials on data access with Flash Builder
      Using data management to synchronize server updates
          Data management tutorial (PHP)
              Create the application and add a DataGrid and Buttons
              Generate and code event handlers for the Buttons