Building Your First PHP-Based Mobile Application

In this tutorial, you are going to create a Flex and PHP mobile application that retrieves, displays, and modifies database records (see Figure 1). A Flex application does not connect directly to a remote database. Instead, you connect it to a data service written in PHP. You will build the front-end Flex mobile application, the database and a PHP class, which is the server-side code used to manipulate database records. You will also run a PHPUnit Test to run and test the methods in your PHP Service to ensure they work properly.
In this module, you are going to build a Flex mobile application that retrieves data from a database and displays it. A list of employees will be displayed in one application view and employee details in another. First, you build the user interface, and then test the application using a desktop emulator.

Figure 1: The completed application.

Prerequisites

1. Install Flash Builder 4.5 for PHP - For more information see the Flash Builder 4.5 for PHP Installation Guide.
2. Zend Server 5.x or above, or a compatible PHP web application server.
   You will need a PHP application server to debug your application. Go to http://www.zend.com/en/downloads/ to downlaod Zend Server 5.x, the Zend PHP application server. For more information see the Zend Server Installation Guide.
   The Zend Server Installer includes optional components that can be downloaded as a part of the installation process.
   The two components you will need for this tutorial are:
• MySQL
• phpMyAdmin

Note:

Make sure to save the username and password for your Zend Server. If you installed the optional components MySQL and phpMyAdmin, the credentials are by default “root” as the username with no password.

3. Download the Building_A_PHP_App.zip file and put the files somewhere accessible. These are all the resources you will need to complete this tutorial.

Step 1: Create a MySQL Databse Using phpMyAdmin

Important Note:

If you already completed Build a Web (PHP) Application, you do not have to repeat this step. The database you created in that tutorial is identical to the database you will be creating here.  

phpMyAdmin is a component that comes bundled with Zend Server in order to handle the administration of your MySQL databases. For more information see Working with phpMyAdmin to Manage MySQL in the Zend Server online documentation. Creating a database in MySQL is necessary in order to debug your Flex/PHP application. The PHP code in your project will use the database to access the information when needed, as defined by the code.

	You will need the test_db.sql file located in the Database folder of the Building_A_PHP_App.zip file. Open your Zend Server UI by entering “http://localhost:10081” into a browser, and enter your username and password. If this is your first time opening Zend Server see Getting Started with Zend Server. Go to Monitor | Dashboard and in the Tasks area click Open phpMyAdmin. Figure 2: Open phpMyAdmin via Zend Server's Dashboard tab phpMyAdmin opens in a new browser. Enter the username “root” and leave the password empty (as defined when setting up your phpMyAdmin during Zend Server installation) and click Go. Figure 3: Import tab in phpMyAdmin GUI Go to the Import tab, browse to the test_db.sql file and click Go. Figure 4: Import tab  The database has been created, and is already located on your machine.
To see the tables located in your database, select the database from the left menu of the phpMyAdmin UI and go to the Structure tab.

Step 2: Create a Flex Mobile and PHP Project

In Flash Builder 4.5 for PHP, use the New Flex Mobile and PHP Project wizard to create a PHP project named PHPMobileService and a Flex project named MobileGettingStarted. Store the project files locally (see Figure 6) and use the default Mobile Settings (see Figure 5).

	In Flash Builder 4.5 for PHP select File | New | Flex Mobile and PHP Project to create a new Flex Mobile and PHP project. Figure 5: Create PHP Project dialog Call the PHP project PHPMobileService and be sure to set the appropriate web root and root URL for a local application server, and validate the configuration (see figure 5). Example server settings: Web Root: /usr/local/zend/apache2/htdocs Root URL: http://localhost Output folder: bin-debug (see figure 6). Click Next and name your Flex project MobileGettingStarted. Leave all other settings as the default. The compiled Flex application location, the output folder, is the bin-debug folder of your Flex project Figure 6: Create Flex Project dialog Click Next and select a View-Based Application with an initial view title of HomeView and specify application settings to reorient and scale automatically for different screen densities with an application DPI of 160 dpi (see Figure 7). Figure 7: Specify mobile settings. Locate and open the MobileGettingStarted-app.xml file that was created and change the id to com.adobe.samples.MobileGettingStarted (see Figure 8). The application ID is used by the AIR runtime and the operating system to identify the application. In order to guarantee a unique application ID, a common naming convention is to use reverse domain name notation as used here. You will modify additional attributes in this file in a later tutorial. Figure 8: Assign a unique application ID. What You Created Flex When you create a new Flex Mobile project, Flash Builder 4.5 for PHP creates three files: two MXML files and one XML file (see Figure 9). You create Flex applications using two languages: ActionScript and MXML. Typically, you use MXML and Flex components to lay out application interfaces and ActionScript to program application logic. MXML tags and ActionScript code can reference each other, similar to HTML tags and JavaScript code. When you compile an application, the MXML is parsed and converted to ActionScript in memory, and then the ActionScript is compiled into bytecode. The result, a SWF file, is rendered by Flash Player for web applications and the Adobe AIR runtime for mobile and desktop applications. Flex mobile applications require the Adobe AIR 2.5 runtime which is available in the Android Marketplace. Figure 9:View the MobileTestDrive project files in the Package Explorer view. MobileGettingStarted.mxml is the main application file. The first line of code is the XML declaration for the parser. The next line is the MobileApplication tag, which is the root container for the Flex mobile application. It has a firstView attribute set to views.MobileGettingStartedHomeView (the second MXML file automatically generated). This is the view that displays on the device when you launch the application. Unlike desktop or web applications built in Flex, you typically do not put much content in the application container. For mobile applications, most content is placed in individual views. The third file created, MobileGettingStarted-app.xml, is the application descriptor file that is used by the AIR runtime when installing and launching the application. It includes info about the application (including its name, id, associated icons, what the initial window should look like and more). PHP When you create a PHP project Flash Builder 4.5 for PHP creates a container where you can create and manage all your PHP resources for your Flex Mobile/PHP application. Your PHP project is created with Zend Framework already built in, along with a services, public and library folder. Your services folder is where you will create and manage all the PHP Services you will use in your application. A PHP Service is a PHP class containing PHP methods. The PHP methods you define in your PHP Service are used as operations for the Flex side of your application. The library folder will contain the business logic of your application. The public folder holds all the public resources of your application, which are all the resources that will be visible to the client. Also included in the public folder is the Gateway script. The gateway is responsible for converting objects and translating the results from PHP methods into native ActionScript objects used in the Flex User Interface. The Zend Framework library is included in the Include Path of your PHP project automatically. You can see this and the resources contained within it by opening the PHP Explorer view (see figure 10). Figure 10: PHP Explorer view

Did you know...

	The gateway script initializes the Zend AMF Server, which is able to translate between Flex/ActionScript and PHP, and the Zend Framework Autoloader which enables dynamic class loading. For more information see The Gateway Script.

Step 3: Download the Mobile Test Drive Assets

	Add the assets folder (available in the Building_A_PHP_App.zip file) under the src folder (see Figure 11). The assets folder contains graphics that you will use in the application. Figure 11: Add the assets folder to your project.

Step 4: Add a TextInput to the Title Area of the ActionBar

	Switch to Design mode for MobileGettingStartedHomeView.mxml and from the Components view, drag out a TextInput and place it in the title area (titleContent) of the ActionBar (see Figure 12). Use the Properties view to assign an id of searchTxt, the text of Employee Name, and a width of 100% (see Figure 14). Figure 12: Add a TextInput to the title area of the ActionBar container. Flex applications are built from components such as Buttons, CheckBoxes, and Lists. The Flex 4.5 framework includes over 70 components, including user interface controls to display content and provide user interaction, and containers to manage the layout. The latest version of the framework includes components and component skins that are optimized for mobile use and in some cases, enhanced to enable touch and throw scrolling. It also contains several new components specifically designed for mobile development including MobileApplication, View, ViewNavigator, and ActionBar. The Flash Builder Component view displays a subset of Flex components recommended for mobile use. The root container of your application, the MobileApplication container, has a single child, a ViewNavigator. The ViewNavigator manages an ActionBar and a set of View instances using a stack-based history mechanism. The ActionBar component is displayed at the top of the application and appears above the views and consists of three areas: a navigator area, a title area, and an action area (see Figure 13). Figure 13:The parts of the ActionBar container. Typically, you place components that let the user navigate the content (like back or home buttons) in the navigator area, a string or other components (like the TextInput used in this application) in the title area, and components that let users take an action (like buttons to search or add employees in this application) in the action area. For each component, you can set properties and styles. Properties apply only to that particular component instance. Styles can be set inline or using CSS to create style rules to apply to your components. You can view and set object properties, styles, and more using the  Properties view (see Figure 14). Figure 14: Use the Properties view to set object properties, styles, and more. Switch to Source mode and take a look at the generated code.

Step 5: Add Buttons to the Action Area of the ActionBar

	Using the Components view, add two Button instances to the action area (actionContent) of the ActionBar (see Figure 15). Assign the first Button an id of searchBtn, delete the label, click the folder icon and select Multi-Resolution Bitmap, and embed search48x48.jpg located in the assets folder for all the dpi's (see Figure 16). Assign the second button an id of addBtn, delete the label, click the folder icon and select Multi-Resolution Bitmap, and embed add48x48.jpg for all the dpi's (see Figure 16). Figure 15: Add Buttons to the action area of the ActionBar container. In the default Properties view (the Standard view), you will not see a way to set the button's icon property. The Standard view displays a graphical interface for setting common attributes of the selected object. To see all the attributes you can set for an object, switch to either the Category or Alphabetical view by clicking one of the buttons in the upper-right corner of the Properties view. Figure 16: Specify multi-resolution bitmaps. If the design area does not update to show the changes made to an object (like the icons you just specified), you can click the Refresh button at the top of the Design mode window to have Flash Builder 4.5 for PHP re-render the screen.

Step 6: Use Spacer Components to Fine-Tune the Layout

	From the Layout folder in the Components view, drag out two Spacer components and drop them to left and right of the TextInput control in the title area. Set widths to 15 and heights to 100% (see Figure 17). Figure 17: Use the Spacer components to finetune the layout.

Step 7: Add a List Control to the View's Content Area

	Using the Components view, drop a List control below the ActionBar. Assign an id of empList and set constraints so that it fills the entire view area (see Figure 18). Figure 18: Set the size and position of a component using constraints. The layout of a container determines how its children are positioned within it. Some containers have a preset layout mechanism (like the VGroup and HGroup containers). For others, like the View container, you can set the layout yourself. For example, you could specify a vertical layout, a horizontal layout, a basic layout , or more. Basic layout uses absolute positioning in which the positions of objects are set using x and y values (the upper-left corner of the container is 0,0) or constraints. Constraints allow you to "pin" an object to a specific location in a container, providing a way to build flexible interfaces. You set constraint properties (top, bottom, left, right, verticalCenter, horizontalCenter) to the number of pixels the object should be from that part of the container.

Step 8: Change Component Attributes in MXML

	Switch to Source mode and use Flash Builder 4.5 for PHP Content Assist to select and set values for various properties and styles. When you place your cursor inside a tag and press the spacebar or Ctrl+Spacebar, you get code hinting with Content Assist (see Figure 19). It shows a list of all the attributes you can set for that tag, including properties, styles, events, and more. Different symbols are used for each different type of attribute. This is the same list you see in the Alphabetical view of the Design mode Properties view. Figure 19: Use Content Assist to see a list of all possible tag attributes.

Step 9: Create Your PHP Project Resources

	In your Library folder, create two PHP file's by going to File | New | PHP File and name them Employee and Department. Copy the Employee.php and Department.php code into the files and save the project. Figure 20: The PHP Explorer view showing your PHP Service and the Department and Employee files.

Step 10: Create Your PHP Service

	In the PHP Explorer view select the services folder in your PHPMobileService project, and from the Right Click Menu select New | Class (see figure 21). Call the file EmployeeService (enter the name in the Class Name text field). Mark the Constructor and the Generate PHPDocBlocks checkboxes (see figure 22), which creates a skeleton in the file in which to add your methods. Figure 21: Select Class from the Right Click Menu of your services folder. Figure 22: The Create New PHP Class dialog. Copy the EmployeeService example code into the file. As this code includes details about your database, edit the values represented in the "" according to the details of your database.

Step 11: Run a PHPUnit Test on Your PHP Service

Running a PHPUnit test will allow you  to test the methods in your PHP service, ensuring that individual methods are working properly. In the same way that you can debug an application to diagnose problems within it, you can run a PHPUnit test to help you diagnose any problems or errors in your PHP class. Testing an individual method is one option (see figure 28), but running a PHPUnit Test will allow you to test all of the methods in the class simultaneously.
In this case, we are using this resource to ensure that our PHP class is working smoothly to prevent any future errors.

	Go the PHP Explorer view and select the EmployeeService class. From the Right Click Menu select New | Other | PHP | PHPUnit | PHPUnit Test Case (see figure 23). Figure 23: Select PHPUnit Test Case from the New wizard. Click the 'Click here to add PHPUnit to the Include Path' option, which will allow the PHPUnit Test to be aware of the resources in your project and functionalities such as Content Assist. In the Element to test field click Browse and write EmployeeService in the search field and select EmployeeService from the list. A file named EmployeeServiceTest has now been created in the services folder of your PHPMobileService project (see figure 24). This file includes methods that are created specifically to run and test the methods in your EmployeeService class. Figure 24 You can see the new test file created for your PHPUnit Test in the PHP Explorer view. Still in the PHP Explorer view select your new EmployeeServiceTest file and from the Right Click Menu select Run as | Run Configurations and double click PHPUnit. Name the configuration EmployeeServiceTest and open the PHP Script tab and select the Alternate PHP option and select the PHP 5.3.3 (CGI) (Zend 5.3.3 CGI) option (see figure 25). Click Apply and Run to run the application. Figure 25: Run the file as a PHPUnit Test to run and test the methods in your PHP Service. The PHPUnit view opens with the results of the test. For a successful test you will see a green bar and the covered lines in the Code Coverage tab (see figure 26). For a failed test, there is a red bar with a list in the Trace failure tab of the specific lines in the code that failed. Figure 26: A successful PHPUnit Test with the lines covered in the Code Coverage tab.

Step 12: Introspect and Bind

After you have created your PHP services, you need to connect it to your Flex project. This makes the methods in the PHP service easily accessible for binding while developing the Flex side of your application. Once you have introspected your PHP service, you can use the methods contained within it as operations for the Flex component's in your applications GUI.
Introspecting PHP services in Flash Builder 4.5 for PHP can be done in two ways; using the Right Click Menu or using the Data/Services view. Here we will go through the process using the Right Click Menu.

	From the Right Click Menu of EmployeeService select Create PHP Service for Flex.  The service details (service name, service package, and data type package) are automatically generated according to the PHP class. Click Next and Finish to complete the PHP Introspection. Your PHP Service is now connected to your Flex project. Select your Flex project in the Package Explorer view, and open the Data/Services view to see all the public methods included in the PHP Service (see figure 27). Figure 27: See all the public methods included in your PHP service in the Data/Services view. Test the method in your service to make sure it is functioning properly by selecting the getEmployee method in the Data/Services view and select Test Operation from the Right Click Menu. In the Test Operation view make sure getEmployee is selected in the Operation dropdown menu and click Test. The test run will show you all the response names and values received (see figure 28). In this case it is the details of each of the employees in the database. Figure 28: The Test Operation view lists all of the names and values received from the specific method you tested. Binding is the process of consuming the PHP methods into your Flex Mobile project by binding the data. This is achieved by tying your existing Flex components to an operation (a PHP method). Flash Builder 4.5 for PHP allows you to bind your data in the following ways: using the drag and drop functionality (see figure 27), by going to Data | Bind to Data after selecting code in the Source view or a component in the Design view, by selecting Bind to Data from the Right Click Menu of a Flex component in the Design view, or by inserting it directly in the code. To bind the data using the drag and drop, open the MobileGettingStartedHomeView.mxml file in Design mode and the Data/Services view. Select the getEmployees function and simply drag into the list you inserted when creating the UI (see figure 29). Figure 29: Use the drag and drop functionality to drag a method directly into the UI. In the Bind to Data dialog select firstname from the Label Field dropdown menu before clicking OK.

Step 13: View a Component's API

	Select Help | Dynamic Help and then click a component tag in your code. In the Help view, click the component's API link to view its API (see Figure 30). The Adobe Help AIR application opens, which allows you to view help content (including the ActionScript Language Reference, ASDocs) when you are online or offline (once the content has been downloaded and saved locally). A component's API, its application programming interface, lists everything you can set for that component and includes descriptions and code examples. If you do not see the class explorer on the left side, click the Show Packages and Class List link in the upper-left corner of the window. Figure 30: View a component's API.

Step 14: Preview the Mobile Application Using the Desktop Emulator

	From the Right Click Menu of your MobileGettingStarted project select Run As | Mobile (PHP) Application. In the Run Configurations dialog box, launch the application on the desktop for a specific mobile device (see Figure 31). Figure 31: Create a run configuration to emulate the application on a specific mobile device. Your application runs in the AIR Debug Launcher (ADL) (see Figure 32). The ADL provides a way for you to run and debug mobile and desktop applications without having to first install them on a computer or device. Figure 32: Preview the application in the AIR Debug Launcher. The ADL also provides menu items in the Device menu to emulate devices and device actions, such as rotating the device or pressing the Back button (see Figure 33). Simulate rotating the device and see the ActionBar automatically resizes to fit the screen. Note that in the emulation the view may look somewhat large because the pixel density of mobile devices is higher than that of desktop monitors. Note: If you do not see the ADL menu, click on Flash Builder and then return to your application and click it. You should now see the ADL menu. Figure 33: Use the ADL Device menu to simulate device actions. Next, simulate the application on a device with a different pixel density. Return to Flash Builder 4.5 for PHP, select Run | Run Configurations, and then in the launch method area click Configure. You should see a table listing screen sizes and densities for common mobile devices (see Figure 34). You can also modify this list to add your own device configurations. Notice the Motorola Droid Pro has a lower PPI and will thus use the 160 dpi assets you specified. The other Motorola Droids will use the 240 dpi assets. Figure 34: View device configurations. Return to the run configuration dialog box and rename the existing configuration to specify a dpi. For example, if it is using the Motorola Droid Pro device, call it MobileGettingStarted (160). Click the New Launch Configuration button in the upper-left corner and create a second launch configuration for a device with a different pixel density, for example MobileGettingStarted (240) for the Motorola Droid X. Run the application. You will see a different size window with an application scaled to the appropriate size and using the appropriate multi-resolution assets.

Step 15: Debug Your Application

Set breakpoints on the getEmployee method in your MobileGettingStarted and EmployeeService files. You are placing breakpoints in both the Flex and PHP code so that the debugger can debug both the server side and client side of your application simultaneously. From the Right Click Menu of your MobileGettingStarted project select Debug As | Mobile (PHP) Application. In the Debug perspective, you will see that the debugger has stopped at the first breakpoint (see figure 35). Click , and then click it again after the next breakpoint is hit. Figure 35: When debugging your Flex Mobile and PHP application, you will see the results in the Debug perspective.