explorers’ club

Preface

If you are no stranger to the concept of a Rich Internet Application (aka. RIA) and the different constituents that make up a RIA, you can skip this introduction. This tutorial will help developers to setup a Flex application to a database using PHP while minimizing manual database queries. Let’s familiarize ourselves with a few basic RIA concepts. Generally a RIA is comprised of 3 main components:

• the client – no, not your client that sends the checks, but rather the Graphical (User) Interface that a user of a RIA interacts with. In our case, this the flex client that is deployed to a particular URL.
• the service layer -this component is the hidden part of the application that interprets client events, requests information stored on a database, and then sends the requested data back to the client. In our case AMFPHP, PHP and POG will be in this category. I will explain what these mean in a bit.
• the database – this is where our data is stored. In my case this is MySQL. Depending on your local setup, you may be using a different database.

For most of this tutorial we will be dealing with the client and the service layer. The service layer will be comprised of AMFPHP which is a very small framework which facilitates remoting between Flex and PHP. Remoting is simply a means to send and receive native ActionScript objects to a service layer. POG is another small framework for taking PHP objects and allowing CRUD methods for their database counterparts. CRUD stands for Create, Read, Update and Delete and POG simply stands for PHP Object Generator. In our case, we are setting up a RIA so that the objects sent to and from Flex will easily be able to be manipulated via CRUD methods. To sum this up we are establishing a seamless means of having Flex and a database to communicate with a minimum amount of manual data manipulation. If that confused the hell out of you, I apologize as I am kinda new to making tutorials.

Resources

POGTestApp client & server – link
AMFPHP v1.9 20070513 – link
POG – link

The Quest

Anyone who frequents this blog know that I have been on a mission for some time to get some sort of ORM setup for my pet-project. I didn’t want to be encumbered by a heavy framework with a complex API or inheritance structure. I’d looked at CakePHP, Doctrine, Propel, Junction and a few others. As a non-PHP guy, I found all of those to be overwhelming. I’d rather spend my time coding than having to read config documentation or learn a new API. That is not to say that I don’t want to learn something new, I do. I just felt enough of my time had been spent trying to find the right solution. The right solution had to be ultra-simple and intuitive.

Enter POG

POG stands for PHP Object Generator. I’ll spare you my praises of it for now (you can read up on their site if you like). Suffice it to say it is an ORM framework that is simple, intuitive and light weight. And it works for me. This looks like a long read, and it is, but it will go rather quickly. Lot’s of pictures too!!!

Your first Flex + AMFPHP + POG RIA

Server setup

I have my project setup in two places. One location is where my deployable flex content, AMFPHP and POG code goes. The other is simply where I house my Flex project source. Here is a pic of the deploy location:

I use MAMP (Mac + Apache + MySQL + PHP) which is a turnkey PHP server. It works well for me because I really didn’t like doing all the Terminal setup to get my Mac’s built in PHP setup for this. If my project makes it to the big time, then all this server side setup will be delegated to a more knowledgeable person who can set it up better than I have.

AMFPHP

Firstly I want to tackle the AMFPHP part since its probably the most straight forward part of the process. Go and download AMFPHP 1.9. I am using the 20070513 release. Once downloaded, unzip it and place it in the aforementioned deploy location. The only things you need to do for AMFPHP is:

• make note of you services folder (I put a symlink to the whole AMF folder in my flex project so I could have direct access to it from within Eclipse without having to use the bin folder).
• adjust the following information on the globals.php
  • $servicesPath – in my case “services/”
  • $voPath – this will point to your POG objects folder once we get it setup, in my case “../pog/objects/”

That is all on the AMFPHP aside from constructing your services.

[EDIT 2008.03.21]

Since initially this tutorial only happened to touch upon the setup of these technologies there hadn’t been any issues encountered. Obviously this tutorial didn’t reflect a real implementation of such a setup beyond the simple Get method. Further development has turned up an interesting find about sending AS3 objects out from Flex to be mapped to a POG object. As it is now, it can’t. That is because the naming convention chosen by the POG framework doesn’t get picked up by the AMFPHP deserializer. My gunslinger buddy Renaun Erickson has found a simple solution for this that doesn’t break the POG naming convention. You can read more about it on his blog – link.

You need to open the AMFBaseDeserializer.php and insert the following code at line 384:

elseif(file_exists($GLOBALS['amfphp']['customMappingsPath'] . 'class.' . strtolower($mappedClass) . '.php'))
{
        $include = $GLOBALS['amfphp']['customMappingsPath'] . 'class.' . strtolower($mappedClass) . '.php';
}

POG

POG is unique in that you don’t just go and download a framework (at least not yet). If you visit POG, you are greeted with a little RIA that takes some information about the object you want to create. I decided to use the name TestObject and give it two properties: userName and password both being varchar(255). Just to reiterate, I am using the PHP5.1+ along with the POG database wrapper:

Notice that I am NOT using the PDO mysql wrapper. Reason being that AMFPHP has issues finding the mysql PDO driver and not everyone’s php environment contains those. So let’s stick to the POG database wrapper.

Since this is the first interaction with POG, we want to download the full framework in addition to you new object:

Then unzip the file, rename it simple as “pog” and place it in your deployment location. Next locate the {yourMainDeploymentFolder}/pog/configuration.php and update the needed information so that POG can access your database. Here is a snap of mine:

Notice that I have my mysql port set to 8889 rather than the default 3306? Also the plugin settings url is an absolute path. In your browser navigate to the following location: http://localhost{:yourPort}/{yourMainDeploymentFolder}/pog/setup/index.php. Go through the initial welcome/setup screen. POG will do some quick unit test, and if everything goes well, you are then presented with a portal to do basic CRUD methods on your new POG object. This is useful because we can setup a few test objects to use in setting up and testing the Flex application.

Now it would appear that POG is ready to go. And you’d be correct if you just want to use the local POG portal to play with it. In order to get it working with Flex and AMFPHP, you need to fix a few things with a few classes in POG. We will come back to that after we get the Flex project setup.

Flex

I am providing my POGTestApp source for you to download, but I also want you to see the steps necessary to do it yourself. First let’s create a new Flex project. I called mine POGTestApp. Now I also have mine located in a different place than the deployment location so I used some advanced options:

In the provided flex project, I have the Cairngorm.swc in the libs folder. Make sure to add the libs folder to the library path. Also point it to the services-config.xml:

Open the services-config.xml and make sure to modify the endpoint uri to point to your amfphp gateway.php:

Now at this point you should be able to modify your Services.mxml (ServiceLocator subclass) and add your php services there. If you downloaded the files I have provided, I suggest taking a look at Services.mxml. Since this is a testing application, I have a genericFaultHandler and a genericResultHandler in this file that you can add breakpoints to for debugging purposes. So even though I am making the calls from the application file without any responders, I am still listening for them in Services.mxml. Now if you decide to make some calls of you own, without using my files, you will notice that you get some errors or it just doesn’t seem to work. That is because POG needs some adjustments to work properly.

POG adjustments

Even though POG works inside the provided POG setup.php, it won’t want to play with Flex or AMFPHP unless you give it some help. Here are a few things to modify:

• open the class.database.php and hardcode your configuration.php settings in there. For some reason the global vars are not making through to the Database class. Since I suck at php, I was advised to put it here until a better solution is found.
• open the class.testobject.php (or whatever your POG object is named) and add the remoting string: var $_explicitType = YourRemotingClassNameHere.
• also add include_once(‘class.database.php’);to class.testobject.php.

That should do it. Make your own or use the POGTestingServices and play with it. Keep in mind that even though my provided files work, you might get some PHP specific errors that appear to fail silently. If you experience this behavior you need to check your php.log to see what the issue is. Generally its due to the remoting code rather than the POG code.

Retrospective

I really like the idea of remoting for prototyping. It takes the hassle away from having to parse your responses in flex. POG is an ideal solution for developers not that familiar with PHP as the objects translate rather easily and since it is OO, its easy to do the mysql input without having to get involved with writing queries.

When time is of the essence, maybe you will consider this beautifully simple solution. Thanks goes out to Joel Wan (POG) and Renaun Erickson (the gunslinger) for help sorting this out. Let me know if you have any advice, suggestions, criticism and or corrections for this tutorial.