I’ve been receiving a number of emails on this topic lately. It seems there is little information out there about how to move from development to production with a Flex and PHP application. Here is a simple checklist that could help you, especially if you are doing this for the first time. Please note that I presume you used the Data Services (wizards) to connect the Flex client to PHP services.

1. Make sure you have Zend Framework on your server. If you don’t, install it
2. Make sure you change MySQL credentials and server IP/name used by your PHP scripts to connect to the database
3. Copy the PHP services folder to your server. Then test these services. If they don’t work check the MySQL credentials or look for dependencies (maybe your PHP services use other PHP classes that you forgot to copy to your server)
4. Edit the amy_config.ini file and make sure the path to the Zend Framework is OK and set production to true
5. Edit the Flex services to point to your live server gateway.php. In the services folder of your Flex project you will find _Super_something.as files. In the constructor you will find a line like this:

   _serviceControl.endpoint = “http://localhost:10088/MobileFlexPHP-PHP/public/gateway.php”;
   Copy that line and then open the class that extends this _Super class and paste the line in the constructor. Then change the URL to reflect your server setup

6. Copy the bin-release/ folder to your server (you should choose the export release for your project; this will create a SWF file smaller than the debug version)

That’s it! If I missed something please drop a comment!

As I promised here are the slides Kevin and I used for today’s webinar:

Here is what we covered:

• Short introduction to this new product – Flash Builder for PHP
• Using the new Flex and PHP project wizard and discussing the generated projects
• “Consuming” a PHP service from Flex
• Building a simple UI to display data stored in the database
• Explaining how the PHP remoting end point is configured (gateway.php)
• Tips and tricks on using PHP doc to help Flash Builder generate the correct data type for return variables, arguments, and value objects.

You can find the recording of the webinar here.

As you might have heard, we released earlier this week Flash Builder and Flex 4.5. Part of this release is a new product called Flash Builder for PHP 4.5. This is something you should make sure you try if you are a PHP and Flash/Flex developer.

So what is Flash Builder for PHP? This product will install Flash Builder 4.5 with Zend Studio 8.1 as a plugin plus some additional plugins that integrate these two products. Using this IDE you can create mixed projects (Flex and PHP both for desktop and mobile devices) and you can streamline testing, deploying, debugging, and consuming PHP services via Flex remoting (with the help of Zend Framework).

Instead of writing a pretty long article, I decide to shoot a video tutorial on how you can create a Flex mobile app that uses a PHP service. This tutorial will walk you through:

• Using the new project type Flex Mobile and PHP
• Creating a mobile application that has two views/screens. I will explain how to use the ViewNavigator and View classes to control your application state
• Consuming a PHP service from a Flex mobile app using remoting
• Testing and debugging the code (Flex and PHP) on the desktop simulator and physical device

I hope you will enjoy this. If you want to download the files used for this tutorial, click here (unzip the file and you will get the Flex project you can import it and the PHP files plus the database dump).

I finally got some time to play with Doctrine 2 and Flex. Back in May I wrote an article about working with Doctrine 1.x and Flex (you can read the article here) and my feelings were mixed. I chatted with Jonathan Wage of Doctrine about some of the shortcomings I found in Doctrine 1.x and his response was to check Doctrine 2 (still in development at the time of writing this article). Doctrine 2 is a big step forward.

In this article I describe how I rewrote the original application I created for my first article, this time using Doctrine 2, Flex 4, Zend Framework, and the Flash Builder data-centric development wizards. I’ll highlight the relevant differences between Doctrine 1 and Doctrine 2 along the way. Thus, you should find this article valuable in any one of these two cases:

• You are already working with Doctrine 1 and you’ve wondered what it would take to move to version 2
• You want to learn how to use Doctrine 2 with Flex; you know PHP and you know enough Flex not to be scared away if you see some snippets of code

Before going into the details let me say this: if you aren’t already using an ORM framework for PHP then you should. For most projects it can help you by freeing you of the tedious tasks of writing CRUD code and SQL queries. It allows you to focus on the business logic of your application. And all these advantages are multiplied when working on Rich Internet Applications because on this kind of project much of the work is done on the client and not on the server.

There are some aspects of using this ORM with RIA that could be better, but hey we don’t live in a perfect world. Most of these things, I think, are related to the fact that every time you use a server side ORM with a rich client, you leave behind the main story used for creating that framework – you use the ORM in order to feed a rich client with data and enable the client to persist the changes. Thus you need additional boiler plate code to make the whole thing work.

If you don’t know much about ORMs in general, you may want to read my first article first and before continuing.

The Big Picture

Here is a screenshot of the application I built running in the browser:

below is the database structure. The only difference between this database and the one used in the previous article is the addition of a simple primary key to the marks table.

While this is by no means a complex application, I think it’s a decent one in terms of relations between tables: I have a number of courses and countries (courses and countries tables), and each student belongs to a country (many-to-one between students and countries) and receives marks for a number of courses (marks many-to-many table for students and courses tables).

The Flex application reads all the data stored in the MySQL database and lets the user fully edit students by performing the following operations:

• Add, edit, delete students
• Change the country for a student
• Change the courses taken by a student and assign marks for a course

And here is an overview of the different parties involved in this application:

Differences between Doctrine 2 and 1.x

Before explaining how I built the app, let’s talk a little bit about the main differences between Doctrine 2 and Doctrine 1.x (as I’m writing this article Doctrine 2 is still in Beta, so things could change).

The biggest change by far is the one related to the main pattern used by the Doctrine 2 ORM. In 1.x versions it used the Active Record pattern (Ruby on Rails uses Active Record too), now you can say goodbye to Active Record and welcome Data Mapper (Hibernate uses the same pattern). What are the differences between these two patterns?

With Active Record the entities know how to persist themselves to the database; basically each entity extends some sort of a class from the ORM framework and implements methods like read(), find(), delete(), and update(). Although it is not mandatory, the entities look very much like the database structure.

With Data Mapper entities know nothing about the persistency layer and nothing about the database structure. The ORM provides the means to persist the entities and read the data into entities (from the database).

From a Rich Client perspective this translates in less work on the PHP side when preparing data for sending across the wire while using Doctrine 2. With Doctrine 1, the data model was heavy due to the Active Record pattern. Thus I had to create a plain vanilla data model used to send the data to the Flex client. In order to efficiently transform the heavy entities used by Doctrine 1 into the plain vanilla ones used for sending the data to Flex, I had to write custom functions. When data came in from the Flex client, the reverse process was needed: use the plain vanilla objects to build the Doctrine entity objects. An alternative could be to send all the data to Flex as arrays. Unfortunately, this approach doesn’t work out of the box; you have to write functions to transform the graph of objects into a graph of arrays/associative arrays.

With Doctrine 2, I don’t need this extra layer of simple value objects and I can return the data as a graph of objects or arrays with the built-in capabilities.

The second big difference is that Doctrine 2 requires PHP 5.3 or newer. Thus, if your setup requires older versions of PHP, then you have to stick with Doctrine 1.x.

Of course the ripples stirred by these two changes are quite big and I think it is safe to say that when moving from Doctrine 1.x to 2 you won’t reuse much of your previous experience with Doctrine 1.x or the code you wrote.

Having said this, I have to say that I, for one, am happy with the evolution of Doctrine, because I favor Data Mapper over Active Record.

Installing Doctrine 2 and creating the PHP project

First of all you need to get the Doctrine framework. There are four different ways (PEAR , Package Download, GitHub, or SVN). Depending on what method you use the configuration of Doctrine will differ a little bit. I used GitHub for my project, and I pulled out the code outside of Apache’s web root.

Speaking of the project, I used Eclipse PDT with Flash Builder 4 (I installed the Flash Builder plug-in on top of Eclipse PDT). The first step after getting the Doctrine framework was creating a PHP project named students-doctrine2. Next I added Flex nature to the project by right-clicking on the project name and choosing Add/Change Project Type… > Add Flex project type from the contextual menu. Make sure you select PHP for the Application Server type and you fill in the path and URL for your web root.

The next step was to create a folder inside the web root where I’ll put the PHP services, entities, and Doctrine’s configuration files: doctrine2_students. Inside of it, I created three folders named entities, proxies, and services. And finally, I created a linked resource between doctrine2_students folder and my Eclipse project (right-click on the project, choose New > Folder and then click on Advance button and navigate to the folder location). With that I was ready to write PHP and Flex code.

The next step is to create a bootstrap file (I call it bootstrap.php and place it inside of the doctrine2_students folder) that configures Doctrine 2 to be usable with my project. This means to load the framework classes, set up database access information, specify entities location and annotation method, and configure the different caches that will be used by the app. In the same bootstrap file I created an instance of the EntityManager class. This is the entry point to the Doctrine 2. If you download the project source code (see the links from the second to last section) you’ll find the bootstrap.php file inside of the doctrine2_students folder. The file looks like this:

<?php

use Doctrine\ORM\EntityManager,

    Doctrine\ORM\Configuration;

$applicationMode = 'development';

//Doctrine Git bootstrap

$lib = '/Users/mcorlan/Documents/work/_git/doctrine/doctrine2/lib/';

require $lib . 'vendor/doctrine-common/lib/Doctrine/Common/ClassLoader.php';

$classLoader = new \Doctrine\Common\ClassLoader('Doctrine\Common', $lib . 'vendor/doctrine-common/lib');

$classLoader->register();

$classLoader = new \Doctrine\Common\ClassLoader('Doctrine\DBAL', $lib . 'vendor/doctrine-dbal/lib');

$classLoader->register();

$classLoader = new \Doctrine\Common\ClassLoader('Doctrine\ORM', $lib);

$classLoader->register();

//additional Symphony components for Doctrine-CLI Tool, YAML Mapping driver

$classloader = new \Doctrine\Common\ClassLoader('Symfony', $lib . 'vendor/');

$classloader->register();

//load entities

$classloader = new \Doctrine\Common\ClassLoader('entities', __DIR__);

$classloader->register();

$classLoader = new \Doctrine\Common\ClassLoader('proxies', __DIR__);

$classLoader->register();

//load services

$classLoader = new \Doctrine\Common\ClassLoader(null, __DIR__ . '/services');

$classLoader->register();

if ($applicationMode == 'development') {

    $cache = new \Doctrine\Common\Cache\ArrayCache;

} else {

    $cache = new \Doctrine\Common\Cache\XcacheCache();

}

$config = new Configuration;

$config->setMetadataCacheImpl($cache);

$driverImpl = $config->newDefaultAnnotationDriver(__DIR__ . '/entities');

$config->setMetadataDriverImpl($driverImpl);

$config->setQueryCacheImpl($cache);

$config->setProxyDir(dirname(__FILE__) .'/proxies');

$config->setProxyNamespace('doctrine2_students\proxies');

if ($applicationMode == "development") {

    $config->setAutoGenerateProxyClasses(true);

} else {

    $config->setAutoGenerateProxyClasses(false);

}

//database connection config

$connectionOptions = array(

    'driver' => 'pdo_mysql',

    'dbname' => 'students',

    'user' => 'mihai',

    'password' => 'mihai'

);

$GLOBALS['em'] = EntityManager::create($connectionOptions, $config);

Creating the PHP entities

With Doctrine 2 (and any ORM that uses the Data Mapper pattern) you have to specify how an entity is persisted by the framework and what relationships it has with other entities (if any). in Doctrine 2 you can choose from four different methods: annotations, YAML, XML, and plain PHP. I initially favored the first one because all the information is stored in the entities classes as PHPDoc comments. Thus if you want to modify an entity you have only one place to look for it. However, after using this approach I think the XML approach is best because you get code-completion hints. Here is the listing for the Course entity (remember I have four tables in my database and I need four entities for my application):

<?php

namespace entities;

/** @Entity 

 * @Table(name="courses") 

 */

class Course {

    /**

     * @Id @Column(type="integer")

     * @GeneratedValue(strategy="AUTO")

     */

    private $id;

    /** 

     * @Column(type="string", length=255) 

     */

    private $name;

    public function getId() {

        return $this->id;

    }

    public function getName() {

        return $this->name;

    }

    public function setName($val) {

        $this->name = $val;

    }

}

Using annotations you specify what table is used for the entity (remember one row from that table will be wrapped in one instance of the entity). You can set different names for the properties if you want (in SQL you don’t use camelCase notation, but in PHP or ActionScript typically you use this convention).

The entities I created closely follow the structure of the database. The only difference is in how the foreign keys are represented. For example, the Student entity, which has a many-to-one relation with the Country entity, doesn’t have a property country_id of type int. Instead, I added a property called country that is of Country type. Similarly, I created a property called marks that holds an array of Mark entities – if a student attends three courses, then its marks property will hold an array of Mark objects with three instances.

Here are some notes on creating entities with Doctrine 2:

• With Doctrine 1 I used the built-in tools to create the domain model from the database structure
• Doctrine 2 has support to create the YAML out of the database schema, and then generate the entities; however I’m not sure it is good idea to do this. If you have complex schemas the generated code might not worked as you expect, and you’ll need to tweak it manually anyway
• You have to remember to set the properties as private/protected and not public, and add getters/setters. If you fail to do this, you might get nasty bugs (Doctrine will have problems injecting the code to handle relations).

Creating the PHP services

With the four entities in place, it is time to create the PHP services. These will be the services used by the Flex client to get and persist data. Basically, using the Zend Framework I’ll be able to invoke remote procedure calls on these objects from the Flex side.

Inside the doctrine2_students/services/ folder I created four PHP files: CountriesService.php, CoursesService.php, MarksService.php, and StudentsService.php.  I edited the bootstrap.php file to load the services folder along with the rest of the files. Here is the listing for the CountriesService class:

<?php

require_once(__DIR__.'/../bootstrap.php');

class CountriesService {

    public function __construct() {

        $this->entityManager = $GLOBALS['em'];

    }

    public function getCountries() {

        $q = $this->entityManager->createQuery('SELECT c FROM entities\Country c ORDER BY c.name');

        return $q->getArrayResult();

    }

}

As you might expect, the complex code is inside of StudentsService class; here’s the public API:

class StudentsService {

    //returns all the students

    public function getStudents() {

        ...

    }

    //save changes for an existent student, or insert a new one

    public function saveStudent($student) {

        ...

    }

    //deletes a student

    public function deleteStudent($student) {

        ...

    }

}

As I said before, the entry point to Doctrine 2 is its EntityManager class. You can use this class to query for persistent objects using different methods. The most powerful method is Doctrine Query Language (DQL) which resembles SQL but works on the entities you’ve defined in your domain model rather than on the underlying tables.

If, for example, you want to retrieve the country with the id equal to 1, you could use this code:

$id = 1;

$dql = 'SELECT c FROM entities\Country c WHERE id = ?1';

$query = $entityManager->createQuery($dql);

$query->setParameter(1, $id);

$countryEntity = $query->getResult();

If you want to change the name for this country, you’d write this code:

$countryEntity->setName('new name for your country');

//persist the changes to database

$entityManager->flush();

If you want to create a new country, you’d write this code:

$countryEntity = new entities\Country();

$countryEntity->setName('Mihai\'s country');

//set the entity to be managed by Doctrine

$entityManager->persist($countryEntity);

//persist the changes to database

$entityManager->flush();

Whith DQL when you write a join, it can be a filtering join (similar to the concept of join in SQL used for limiting or aggregating results) or a fetch join (used to fetch related records and include them in the result of the main query). When you include fields from the joined entity in the SELECT clause you get a fetch join. Here is the code for the StudentsService->getStudents() method:

$dql = "SELECT s, c, m, e FROM entities\Student s 

            JOIN s.country c JOIN s.marks m

            JOIN m.course e ORDER BY s.lastName, s.firstName";

$q = $this->entityManager->createQuery($dql);

return $q->getArrayResult();

Each student is retrieved along with the country he belongs to and all of his courses from the many-to-many table – all with a single DQL query. And if you print_r() the result you’ll see a structure along these lines:

In addition, when you create these kinds of queries with fetch joins and you use getArrayResult() method on the query object instead of getResult(), you get a nice array or associative array of other arrays. These data are ready to be sent to the Flex client without any transformation.

The only part I haven’t discussed is how I handle the changes for a Student. I will talk about this as part of the Flex client.

For the communication between the Flex and PHP side I’ll use remoting. On the PHP side I need Zend AMF in order to enable remoting. But for the purposes of this article I will let Flash Builder 4 handle this (installing Zend Framework and creating the gateway for exposing the four PHP services I created).

Creating the Flex client

With the server code in place, it is time to add the Flex code. In the previous article I wrote all client code manually. This time I’ll use the data-centric development features of Flash Builder to introspect PHP classes and create the service wrappers as well as the ActionScript value objects.

The easiest way to do this, is to first create the four services, and then to define the return types for the getStuff() operations. Follow these steps:

1. From the Data/Services view click the Connect to Data/Service link for the first service or on the third icon (the one with a + sign) for the other three services
2. When the wizard opens, select PHP, and click Next. If it is your first time using the wizard for PHP, then you’ll be presented with a dialogue to install the Zend Framework
3. Click Browse and select the first PHP service
4. Repeat these three steps until you have defined all the four services. Please note that you can change the packages where the services and the value objects will be created

Now, it is time to define the value objects I’ll use on the Flex side. Again I’ll use the data-centric development features:

1. Because the StudentsService returns a complex type that uses Student, Course, Country, and Mark it is important to start defining the return types first with CountriesService and CoursesService, then for MarksService, and finally for StudentsService
2. To define the return type for an operation on as service, expand the tree for the service, and right-click the operation (for example, select getCountries() from CountriesService) and choose Configure Return Type from the context menu. When the wizard opens, make sure the first option is selected on the first screen (Auto-detect the return type from the sample data) and click Next
3. On the second page you can enter a name for the value object class (for example Country)
4. The most complex type is the return type for the StudentsService.getStudents() method. For this one, on the second page of the wizard you need to expand the nodes and choose for the type column, the types you defined earlier (Course, Country, or Mark)

Here is how the Student value object is presented in the Data/Services view after finishing the above steps:

With the service wrappers and value objects in place, it is time to take care of the application UI and put these files to use. For this task I reuse most of the code I wrote in my previous application. I had to tweak some of the methods a little (for example, saveStudent() and onStudentSelection()).

When the application starts, the first thing I want it to do is load the courses, countries, and students. To do so, I created an init() function and registered it on the creationComplete event of the application. Then, I selected the getStudents() method from the Data/Services view, right-clicked it, and chose Generate Service Call. This command adds to the code an instance of StudentsService, an instance of CallResponder (you use this object to retrieve the result using the lastResult property or to register a result/fault listener for that operation), and a method that makes the call to the selected operation and assigns the token returned by the operation to the token property of the CallResponder object:

private function getStudents():void {

    getStudentsResult.token = studentsService.getStudents();

}

…

<s:CallResponder id="getStudentsResult"/>

<services:StudentsService id="studentsService"

fault="Alert.show(event.fault.faultString + '\n' + event.fault.faultDetail)" showBusyCursor="true"/>

Another change from the first article is the use of bidirectional binding for the firstName, lastName, and registration fields of the form.

Here is the complete code of the Main.mxml where the magic happens:

<?xml version="1.0" encoding="utf-8"?>

<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"

               xmlns:s="library://ns.adobe.com/flex/spark"

               xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600" xmlns:services="org.corlan.services.*"

               creationComplete="init()" xmlns:entities="org.corlan.entities.*">

    <fx:Declarations>

        <s:CallResponder id="getStudentsResult"/>

        <services:StudentsService id="studentsService" fault="Alert.show(event.fault.faultString + '\n' + event.fault.faultDetail)" showBusyCursor="true"/>

        <s:CallResponder id="getCountriesResult"/>

        <services:CountriesService id="countriesService" fault="Alert.show(event.fault.faultString + '\n' + event.fault.faultDetail)" showBusyCursor="true"/>

        <s:CallResponder id="getCoursesResult" result="onCourses()"/>

        <services:CoursesService id="coursesService" fault="Alert.show(event.fault.faultString + '\n' + event.fault.faultDetail)" showBusyCursor="true"/>

        <entities:Student id="student"/>

        <s:CallResponder id="deleteStudentResult" result="getStudents()"/>

        <s:CallResponder id="saveStudentResult" result="getStudents()"/>

    </fx:Declarations>

    <fx:Script>

        <![CDATA[

            import mx.collections.ArrayCollection;

            import mx.controls.Alert;

            import mx.events.FlexEvent;

            import mx.events.ListEvent;

            import org.corlan.entities.Country;

            import org.corlan.entities.Course;

            import org.corlan.entities.Mark;

            import org.corlan.entities.Student;

            private var marks:Array;

            private function onCourses():void {

                marks = new Array();

                var c:Array = (getCoursesResult.lastResult as ArrayCollection).toArray();

                for (var i:int=0; i<c.length; i++) {

                    marks.push(

                            {id : 0, mark : 0, course : c[i]}

                        );

                }

                dgMarks.dataProvider = marks;

            }

            private function customLabel(data:Object, column:DataGridColumn):String {

                var arr:Array = new Array();

                var c:int = (data as Student).marks.length;

                var mark:Mark;

                for (var i:int = 0; i<c; i++) {

                    mark = (data as Student).marks[i] as Mark;

                    arr.push(mark.course.name);

                }

                if (arr.length > 0)

                    return arr.join(", ");

                return "NONE";

            }

            private function init():void {

                getCountries();

                getCourses();

                getStudents();

            }

            private function getStudents():void {

                getStudentsResult.token = studentsService.getStudents();

            }

            private function getCountries():void     {

                getCountriesResult.token = countriesService.getCountries();

            }

            private function getCourses():void {

                getCoursesResult.token = coursesService.getCourses();

            }

            private function saveStudent():void {

                var m:Mark;

                student.marks = new ArrayCollection();

                for (var i:int = 0, l:int = marks.length; i<l; i++) {

                    if (marks[i]["mark"] > 0) {

                        m = new Mark();

                        m.course = marks[i]["course"];

                        m.mark = marks[i]["mark"];

                        student.marks.addItem(m);

                    }

                }

                student.country = country.selectedItem as Country;

                saveStudentResult.token = studentsService.saveStudent(student);

            }

            private function onStudentSelection(e:ListEvent):void {

                student = e.itemRenderer.data as Student;

                if (student.country) {

                    var l:int = getCountriesResult.lastResult.length;

                    for (var i:int = 0; i<l; i++) {

                        if (getCountriesResult.lastResult[i].id == student.country.id) {

                            country.selectedIndex = i;

                            break;

                        }

                    }

                }

                if (student.marks && student.marks.length > 0) {

                    var k:int = marks.length;

                    var o:Object;

                    for (var j:int = 0; j<k; j++) {

                        o = marks[j];

                        o["mark"] = 0;

                        for (var jj:int = 0; jj < student.marks.length; jj++) {

                            if ((student.marks[jj] as Mark).course.id == (o["course"] as Course).id) {

                                o["mark"] = student.marks[jj].mark;

                                break;

                            }

                        }

                    }

                    dgMarks.dataProvider = marks;

                }

            }

            private function deleteStudent():void {

                if (!student || !student.id)

                    return;

                deleteStudentResult.token = studentsService.deleteStudent(student);

            }

        ]]>

    </fx:Script>

    <mx:DataGrid id="dgStudents" x="13" y="14" dataProvider="{getStudentsResult.lastResult}"

                 itemClick="onStudentSelection(event)">

        <mx:columns>

            <mx:DataGridColumn headerText="First" dataField="firstName"/>

            <mx:DataGridColumn headerText="Last" dataField="lastName"/>

            <mx:DataGridColumn headerText="Country" dataField="country.name"/>

            <mx:DataGridColumn headerText="Courses" labelFunction="customLabel" width="200"/>

        </mx:columns>

    </mx:DataGrid>

    <s:Button click="getStudents()" label="Get Students" x="13" y="200"/>

    <s:Button x="112" y="200" label="New" click="student = new Student();"/>

    <s:Button x="190" y="200" label="Delete Selected Student" click="deleteStudent()"/>

    <mx:Form x="510" y="0">

        <mx:FormItem label="First:">

            <s:TextInput id="first" text="@{student.firstName}"/>

        </mx:FormItem>

        <mx:FormItem label="Last:">

            <s:TextInput id="last" text="@{student.lastName}"/>

        </mx:FormItem>

        <mx:FormItem label="Registration:">

            <mx:DateField id="registration" selectedDate="@{student.registration}"/>

        </mx:FormItem>

        <mx:FormItem label="Country:">

            <s:List id="country" dataProvider="{getCountriesResult.lastResult}" labelField="name" height="150"/>

        </mx:FormItem>

        <mx:FormItem label="Marks:">

            <mx:DataGrid id="dgMarks" editable="true">

                <mx:columns>

                    <mx:DataGridColumn headerText="Course" dataField="course.name" editable="false"/>

                    <mx:DataGridColumn headerText="Mark" dataField="mark" editable="true"/>

                </mx:columns>

            </mx:DataGrid>

        </mx:FormItem>

        <mx:FormItem>

            <s:Button label="Save" click="saveStudent()"/>

        </mx:FormItem>

    </mx:Form>

</s:Application>

Now, when I call the saveStudent() method I make a call to the remote operation (saveStudent() from the StudentsService.php) and pass along an instance of the Student ActionScript class. In the PHP method (StudentsService->saveStudent()) I get an anonymous Object, so I had to manually build an instance of the Student entity and populate it with the data. Here is the complete code for the server side saveStudent() method:

public function saveStudent($student) {

    if ($student->id) { //update

        $entity = $this->entityManager->find('entities\Student', $student->id);

        if (!$entity)

            throw new Exception('Error saving student!');

        $marks = $entity->getMarks();

        foreach ($marks as $mark) { //update mark value for existent records

            $found = false;

            foreach ($student->marks as $record) {

                if ($mark->getCourse()->getId() == $record->course->id) {

                    $mark->setMark($record->mark);

                    $found = true;

                    $key = array_search($record, $student->marks, true); //remove the $record from array

                    if ($key !== false)

                        unset($student->marks[$key]);

                    break;

                }

            }

            if (!$found) { //remove current mark

                $entity->removeMark($mark);

                $this->entityManager->remove($mark);//remove mark from database

            }

        }

    } else { //insert

        $entity = new entities\Student();

        $this->entityManager->persist($entity);

    }

    $this->addNewMarks($entity, $student); //add new marks if any

    $entity->setFirstName($student->firstName);

    $entity->setLastName($student->lastName);

    $d = new DateTime();

    $d->setTimestamp($student->registration->getTimestamp());

    $entity->setRegistration($d);

    $country = $this->entityManager->find('entities\Country', $student->country->id);

    if (!$country)

        throw new Exception('Error saving student; invalid country!');

    $entity->setCountry($country);

    $this->entityManager->flush(); //save the student

}

If you think it is way to much code for this “simple” operation, then I think you are partially right. In the Conclusions section I touch on this. However you have to remember that this code handles many things: creating a new student, and inserting its marks in the Marks2 table or updating a student and its marks from the Marks2 table if they were changed (new courses added, grade changes and so on).

Instead the delete method is quite clean (remember that behind the scene removes all the related records from the marks many-to-many table):

public function deleteStudent($student) {

    $entity = $this->entityManager->find('entities\Student', $student->id);

    if (!$entity)

        throw new Exception('Error deleting student!');

    $this->entityManager->remove($entity);

    $this->entityManager->flush();

}

Getting the source code

If you’re curious and you want to explore the code, you can download the project from here. It contains the PHP doctrine2_students folder, the database SQL dump for creating the tables, and the Flex code.

The easiest way to import this project is just to extract the folders (you import the project in Flash Builder). Then place the PHP code (doctrine2_students folder) inside of the web root folder. Get the Doctrine 2 files, and then reconfigure the doctrine2_students/bootstrap.php file to define the Doctrine 2 location and update the database credential. And finally, create a new Flex/PHP project, and repeat the first part of the article (creating the Flex wrapper services and value objects).

Conclusions

Overall, I think Doctrine 2 makes it easier to work on PHP and Flex projects. I especially love the new Data Mapper approach and its flexibility/power. The entities are very light and you can easily use DQL in conjunction with getArrayResult() to build a data structure ready for sending to Flex. Also there is no need for all the plumbing work I did for Doctrine 1 in order to send the objects on the PHP side. I encourage you to read the excellent documentation you’ll find on Doctrine site to better understand the inner workings, the different types of associations, and in general the features it offers.

With Doctrine 2 you get a big boost in terms of writing the PHP services and exposing the data to the Flex client. And if you think about it, the server side is not the place where the most the effort goes in. So it is a good thing to have a framework that standardize the PHP code and helps you big time when retrieving and persisting data. However, you can tell that it is not a framework architected with rich clients in mind (and there is nothing bad in this, I mean it’d be the same with the most of the frameworks out there). As easy it is retrieving data from the underlying persistence layer and sending them to a rich client, as hard persisting the client changes is. You have to write custom code to create the PHP entities out of the data received from the client before being able to persist the changes. What I feel it is missing is a way to use a data structure (for example an associative array) as the source for creating the PHP entities (more on this below).

Another interesting departure from the Doctrine 1 example is that I didn’t create an exact match between the ActionScript and PHP entities. When I designed the two sides of the equation, I had in mind the best domain model to serve the Flex client because all the information is edited on the client. Then I used the getArrayResult() method to send associative arrays to Flex (which are deserialized into Objects in Flex).

A feature I stayed away instinctively (both with Dotrine 1 and 2) was the ability to generate the database schema using the entities and the mapping between them. In other words, you could start your project first writing the PHP data model, and then use Doctrine to generate the database for you. I’m old school and all my experience taught me that relational databases treat you well if you treat them well. Thus, I much prefer to create the database with my “own” hands and make sure I set all the indexes/constraints I need. Having said this, I’m not saying that the Doctrine feature for generating database schema is buggy or worthless. I just wanted to explain why I haven’t tried. Your mileage could vary on this one.

The data-centric development features of Flash Builder simplified the creation of the data model a lot. I’m not sure if they work for any kind of project, but in this case I didn’t see any drawbacks.

You have very little work to do when handling the Delete and Read part of the CRUD operations on the server side. However, with Create/Update things change, especially when the object has associations (many-to-many, one-to-many, many-to-one with other entities). I thought it would be enough to retrieve the existing Student data from Doctrine and call the removeMark() method to remove a Mark. In fact, doing this doesn’t delete the entry from the many-to-many table. Instead, you have to explicitly remove the Mark instance from the Student and from the entityManager:

$student->removeMark($mark);

$this->entityManager->remove($mark);

Doctrine 2 offers a Cascade feature for persist/remove. For example, here I defined cascade delete/update for the Marks entities on the Student object:

class Student {

...

    /**

    * @OneToMany(targetEntity="Mark", mappedBy="student", cascade={"persist", "remove"})

    */

    private $marks;

...

}

However, I found that they actually work perfectly only on delete (see the previous paragraph for why I don’t believe the persist is fully functional). It is possible that I didn’t understand the usage, and I was expecting more than intended or I just messed up something…

Another small glitch was related to the composite primary keys. When I tried to follow Doctrine’s documentation and annotate the Mark entity to compose the primary key out of student_id and course_id, I got a runtime error. So I had to alter the table and add an auto increment primary key.

The only other thing I didn’t like was the date handling. When you send a Date object to the PHP side, on the PHP side you get a Zend_Date object (when using the Zend Framework). And because Doctrine 2 knows how to handle only the PHP DateTime object, you have to manually handle the transformation. It would be cool to either configure in some way Zend Framework to use PHP DateTime instead of Zend_Date or to have Doctrine 2 handle this for you :D

I had tons of fun while writing this article and playing with this new technology. I can say that Doctrine 2 rocks! If you give Doctrine 2 a try with Flex, please drop a comment with your impressions.

Later Update: If you are looking for an article rather on Doctrine 2 than Doctrine 1, then check this one.

This year I finally had the time to play with Doctrine (version 1.x) and Flex. Actually, it was more than playing; I’m using it for a real project that hopefully will enter production pretty soon. To summarize the experience in just a few words: it’s mind-blowing.

OK, I admit I may be exaggerating a little bit. Still, it is something that can change the way you build projects. Doctrine is an ORM (Object Relational Mapper) framework for PHP and it can really speed up the server side development when you have a lot of tables in your database.
In this article, I explore how to work with Doctrine on the server side, Flex on the client side, and remoting to communicate between Flex and PHP (using the Zend Framework for remoting on the PHP side). I also want to share with you some tools and workflows that can save you some time. While most things are fairly straightforward there are a number of tips and tricks that you may find useful if you decide to go down this road. (I will show you how to use plain vanilla value objects and how to handle dates just to give you two examples. Why reinvent the wheel?)

The application I’m going to build in this article is simple but the workflow is the same one I used with a much more complex application. Having said that let’s start by understanding the big picture.

1. The Big Picture
2. Database Model
3. Installing Doctrine
4. Configure Doctrine and generate the model files
5. IDEs: Eclipse PDT and Flash Builder 4
6. Creating the PHP services and PHP value objects
   1. Getting the countries and courses
   2. Creating the StudentsService service
   3. Handling Create, Update, and Delete with Doctrine
7. Installing the Zend Framework
8. Setting up the gateway file
9. Creating the Flex front-end
   1. Creating the ActionScript value objects
   2. Creating the UI
10. Getting the source code
11. Conclusions

The Big Picture

Let’s see how these different pieces come together and play nice with each other like one big happy family. Have a look at Figure 1. Yeah, this is what you’ll get if you follow this article.

Breaking down Figure 1:

• On the right is a MySQL database to persist the data. You’ll see the data model in the next chapter.
• On the PHP server I use Doctrine to manage the tables in the database. I use Doctrine features to generate the model classes out of the database structure.
• On the PHP server I have a bunch of PHP services, which will be consumed from Flex using remoting. Typically for each table from the database there is a PHP class that provides, at a minimum, basic CRUD operations (Create/Read/Update/Delete).  These PHP services use the Doctrine model classes to read and persist the data. They are completely unaware of the database structure.
• Finally, we have plain vanilla PHP value objects. These may follow the structure of the database. The Doctrine models return instances of these value objects. The PHP services, when called from the Flex side, receive instances of these classes as arguments.
• The last piece on the PHP server is the Zend Framework. I use this framework to enable remoting for PHP (you could use AMFPHP, WebORB for PHP, or Sabre AMF as well). Basically it provides a gateway that represents the entry point to the PHP services for the Flex application.
• On the Flex side there are RemoteObjects that map to the PHP services.
• Then I have ActionScript value objects. For each PHP value object there is a corresponding ActionScript object. When using remoting the data is automatically changed to the right type based on the mappings you define.
• I can bind these ActionScript value objects to the different user interface elements in my application.

[Top]

Database Model

It is time to create the database. I’m going to use MySQL for the database. Every time I start a project that someday will be in production and uses a database I use data modeling software. Eight years ago the only viable solutions were Erwin or Power Designer (at least to my knowledge). I found that MySQL Workbench does a decent job and I use it fairly regularly nowadays (you can download MySQL Workbench from here).

Why use  database modeling software? It helps you design the database and all the dependencies, share the design with others, and quickly remember the database structure when you go back to the project after couple of months off. And it helps you a lot when you start to change the project as you are in the middle of it. Remember that I’m talking about projects that go into production, and I think there are very few of those that don’t undergo modifications, including changes to the database structure.

You can use MySQL Workbench to create a data model from scratch or reverse engineer an existing database. You can push all the changes you make to the model (new tables/fields/indexes) directly to the database. And, of course, you can print these models.

To start a new model, choose File > New and then click Add Diagram if you want to start from scratch. Then you can use the toolbox on the left to add tables and draw the relationships between them. When you double-click a table you can edit the name or add/edit fields and indexes. On the right side there is a Catalog viewer. By default the model will try to create the tables into a database named mydb. If you want to change the name of the database you can double-click on the current name from the Catalog view.

Once you’ve finished the design of the data model you can add a connection to your database server. The server can be on the localhost or a remote host, in the latter case you need to be careful if you have firewalls. Next use the Database > Synchronize Model wizard to push the new database model to the database server. You can use the same wizard whether you make changes to the data model and need them reflected to the database or you change the database and you want to push them to the data model.

You can download the model I created (see Figure 2) from here.

My application has four tables: students, countries, marks, and courses. A student can be registered to many courses and the mark (or grade) for each student for each course is stored in the marks table (a many-to-many table). Each student originates from a country, and there is a one-to-many relationship between the countries table and students table.

It is always a good practice to ensure that the data are consistent by using all the means a relational database offers (foreign keys, unique keys, and so on). I have unique keys for the name field in the countries and courses tables, on the first_name and last_name fields in the students table.

Now that I have the database in place and I can easy change it using the model, it is time to create the PHP classes that will handle these tables. Which means it is time for Doctrine to take the stage.

[Top]

Installing Doctrine

Doctrine is one of the few PHP ORMs (Object Relational Mapper) available. The current version (at the time of writing this article) is 1.2.2. You can download it from here. You can also get the library using SVN (here is the link for the repository; you need to look under the tags node).

Why should you consider using Doctrine (or any other ORM for that matter)? Usually, any change you make at the database level will require a change to the PHP code that handles that database. Doctrine can isolate you from these changes. How? It has a feature that lets you generate PHP classes that handle each table from the database, and the input for this feature can be the database itself.

Suppose you add a new table and two new fields in existing tables. You do this in MySQL Workbench, then you use the MySQL Workbench synchronize feature to push all these changes to the database. Next you use Doctrine to generate again the PHP classes that handle this database. In just a couple of minutes you have all the code you need to perform CRUD operations on your tables.

Doctrine also takes care of escaping the values, thus protecting you from SQL injection attacks. Another cool feature of Doctrine is DQL (Doctrine Query Language). This feature makes it easy to write complete queries.

You may be thinking that using the layers on top of PHP (Doctrine and the Zend Framework) can degrade the performance of your application, including how fast it responds to a request, how many clients can connect, and so on. While this is true theoretically speaking, in practice I’d say that the vast majority of projects don’t have performance issues. They have problems keeping up with design changes and new features.

Once you have the library files, create a new folder called doctrine_students under your web root folder. Inside of this folder create these folders: lib, lib/vendor, and lib/vendor/doctrine/. Next copy the Doctrine files to the doctrine_students/ lib/vendor/doctrine/  folder. If you downloaded the archive file, then you have to copy the folders and files from Doctrine-1.2.2/Doctrine-1.2.2/lib/ (there should be a Doctrine.php file and a Doctrine folder).

You can read more about installing Doctrine here.

[Top]

Configure Doctrine and generate the model files

The configuration of Doctrine is pretty simple. Basically you have to create a bootstrap file and include the Doctrine.php file, and then set the credentials for the database.

I created a file called bootstrap.php inside of the doctrine_students folder. This bootstrap file will be required in any PHP file that uses Doctrine. Inside of this file I added the following code:

<?php

//require the main file from Doctrine

require_once(dirname(__FILE__) . '/lib/vendor/doctrine/Doctrine.php');

//register the class autoloader function

spl_autoload_register(array('Doctrine', 'autoload'));

//create the singleton Doctrine_Manager instance

$manager = Doctrine_Manager::getInstance();

// enable automatic queries resource freeing

$manager->setAttribute(Doctrine_Core::ATTR_AUTO_FREE_QUERY_OBJECTS, true);

Next, create a new PHP file called generate_model.php inside of the doctrine_students folder and add this code as a simple test:

<?php

require_once('bootstrap.php');

echo Doctrine::getPath();

If you navigate to the doctrine_students folder in a terminal/console window and run generate_model.php you should see the absolute path to the doctrine folder:

mcorlan-mac:doctrine_students mcorlan$ php generate_model.php

/Applications/MAMP/htdocs/doctrine_students/lib/vendor/doctrinemcorlan-mac:doctrine_students mcorlan$

Create a new folder called models inside of doctrine_students. This is where Doctrine will generate the model files. Then go back to bootstrap.php file and add a new line at the end to create a database connection:

//create a connection

$conn = Doctrine_Manager::connection('mysql://mihai:mihai@127.0.0.1/students', 'doctrine');

Basically you set the connection type to mysql, then you set the user and password (in my case “mihai” for both) then you set the database IP (don’t use localhost even if you have MySQL installed on your local machine because it will not work), and finally you specify the name of the database to be used.

Back in the generate_model.php file, comment out the echo line and add these lines:

//generate the models from the DB schema in the models folder

Doctrine_Core::generateModelsFromDb('models', array('doctrine'), array('generateTableClasses' => true));

In your console, run php generate_model.php and you should find in the doctrine_students/models/ folder a bunch of files and another folder named generated. Basically you have a file with the same name for each table from your database. You will see in the next chapter how to use these model files to persist and retrieve data.

Having generated the model files, I want to load them by adding these lines to the bootstrap file (at the end of the file):

//include the models

Doctrine_Core::loadModels(dirname(__FILE__) . '/models/generated');

Doctrine_Core::loadModels(dirname(__FILE__) . '/models');

Doctrine offers another way for creating these model files: YAML schema files. You can write a schema file from scratch and then use this file for generating the models. Alternative, you can use the models you generated using the database structure to create a schema file and then edit this file before using it to regenerate the models.

If you want to create a schema file, just edit the generate_model.php file as follows (I commented the line that generates the model from the database and I added a new line that creates a YAML file from the models):

<?php

require_once('bootstrap.php');

//echo Doctrine::getPath();

//generate the models from the DB schema in the models folder

//Doctrine_Core::generateModelsFromDb('models', array('doctrine'), array('generateTableClasses' => true));

//generate the Doctrine Schema from models

Doctrine_Core::generateYamlFromModels('schema.yml', 'models');

Return to the console and execute the following command again: php generated_model.php. After this you’ll find a schema.yml file inside of doctrine_students folder.

With all the models in place, it is time to see how you can use these files to manage the database.

[Top]

IDEs: Eclipse PDT and Flash Builder 4

Up until now you could have used just about any text editor to complete the steps I’ve outlined. As the code you write gets more complex (and soon you will start to write Flex code as well), it is time to introduce you to my favorite setup for working on Flex and PHP projects: Eclipse PDT + Flash Builder 4 plug-in + XDebug (for enabling PHP debugging).

The easiest way to install Eclipse PDT and Flash Builder together is to first grab the Eclipse PDT and then install the plug-in version of Flash Builder on top of  Eclipse PDT. You can read more about how to install these products together here.

Now that you have support for both PHP and Flex projects, create a PHP project using the PHP new project wizard from Eclipse PDT (select the PHP perspective and choose File > New > PHP Project). I named the project students.

Then  add the doctrine_students folder to the project. Right-click the project name in Eclipse and choose New > Folder. When the wizard opens, click the Advanced button and then select the Link To Folder In The File System option. Next, click Browse, select the doctrine_students folder, and click Finish (see Figure 3).

Then create another two folders inside of doctrine_students folder: services and vo (see Figure 4).

[Top]

Creating the PHP Services and PHP value objects

It is time to create the PHP services. I’ll use the model files that Doctrine generated earlier.

First I will create a PHP class with two methods: getCourses() and getCountries(). In many applications you have some tables that stores data that almost never changes, for example lists of countries or cities. For such tables, you don’t need to implement CRUD operations you just need the read method. This is the case with the courses and countries tables.

[Top]

Getting the countries and courses

Create a file named CatalogService.php inside the doctrine_students/services/ folder and add this code:

<?php

require_once(dirname(__FILE__) . '/../bootstrap.php');

class CatalogService {

    public function getCourses() {

        $q = Doctrine_Query::create()

                ->select('*')

                ->from('Courses')

                ->orderBy('name');

        $ret = $q->execute(null, Doctrine_Core::HYDRATE_ARRAY);

        return $ret;

    }

    public function getCountries() {

        $q = Doctrine_Query::create()

                ->select('*')

                ->from('Countries')

                ->orderBy('name');

        $ret = $q->execute(null, Doctrine_Core::HYDRATE_ARRAY);

        return $ret;

    }

}

If this is your first time using Doctrine you’ll probably find this code both strange and familiar at the same time.

As I said earlier, Doctrine offers a query language (DQL). You can learn more about DQL here. The code above uses DQL to retrieve all the records from the courses and countries tables. Some things to remember:

• When you set the from clause (for example, ->from(‘Countries’)) you don’t specify the actual table name but the name of the model PHP class generated by Doctrine to manage that table. In this case it happens to have the same name and the first letter is capitalized.
• DQL works with objects and generates objects or graphs of objects.
• You can control the result format for a query by setting the second parameter of the execute() method on Doctrine_Query. I want to have the result sets as arrays or associative arrays. You could have your own hydration method or you could use one of the built-in hydrators.
• If you want to see the actual SQL that is executed you can call this method: $q->getSqlQuery().

Add some records to the courses and countries tables or use this script to create the database.

Now, you’re ready to test this code. Usually I do this before trying to connect to the PHP code from a Flex application. Just add some simple code at the top of this file in order to initialize the CatalogService object and call the two methods:

$service = new CatalogService();

print_r($service->getCourses());

print_r($service->getCountries());

If you run CatalogService.php in the browser you should see  the courses and countries used in the two tables (see Figure 5).

I have the first service in place, but I’m not entirely satisfied with the way my service works. I want to use some simple value objects to wrap each record instead of having an array of associative arrays like I have now.

I create two value objects called Country and Course in the doctrine_students/vo/ folder:

<?php

//Country.php

class Country {

    public $id;

    public $name;

}

<?php

//Course.php

class Course {

    public $id;

    public $name;

}

Now I just have to create a function that transforms the arrays I get from the Doctrine_Query object into arrays of value objects. You could achieve this by creating a custom hydration method or processing the result you get from the array hydration method.

Here’s how I did it. I created a function called  prepareForAMF that accepts two arguments. The first is the array you get using the Doctrine_Query object and the second is an array of objects to be used to wrap the associative array. From this array the function retrieves the types it has to use to transform the associative array into objects.

Here is the code for this function:

function prepareForAMF($data, $arrTypes) {

    if (count($data) == 0)

        return $data;

    $ret = array();

    $substract = false;

    if (!array_key_exists('0', $data)) {

        $data = array($data);

        $substract = true;

    }

    for ($i=0; $i<count($data); $i++) {

        $o = new $arrTypes[0]();

        foreach ($data[$i] as $property => $value) {

            $pproperty = strtolower($property);

            if (!property_exists($o, $pproperty)) {

                continue;

            }

            if (array_key_exists($property, $arrTypes)) {

                if ($value == NULL) {

                    $o->$property = array();

                    continue;

                }

                $newArr = $arrTypes;

                $newArr[0] = $arrTypes[$property];

                $o->$pproperty = prepareForAMF($value, $newArr);

            } else {

                $o->$pproperty = $value;

            }

        }

        $ret[] = $o;

    }

    if ($substract)

        $ret = $ret[0];

    return $ret;

}

I chose to declare this function in the bootstrap.php file because this file is already included in all the PHP services.

Having this function defined I rewrote the methods from CatalogService like this:

public function getCourses() {

    $q = Doctrine_Query::create()

            ->select('*')

            ->from('Courses')

            ->orderBy('name');

    $ret = $q->execute(null, Doctrine_Core::HYDRATE_ARRAY);

    $ret = prepareForAMF($ret, array(0 => 'Course'));

    return $ret;

}

public function getCountries() {

    $q = Doctrine_Query::create()

            ->select('*')

            ->from('Countries')

            ->orderBy('name');

    $ret = $q->execute(null, Doctrine_Core::HYDRATE_ARRAY);

    $ret = prepareForAMF($ret, array(0 => 'Country'));

    return $ret;

}

Next you need to include the two value objects in the CatalogService.php class by adding these lines at the top of it:

require_once(dirname(__FILE__) . '/../vo/Country.php');

require_once(dirname(__FILE__) . '/../vo/Course.php');

If you run CatalogService.php in the browser you’ll see the courses and countries are now listed as objects (see Figure 6).

Note: In Doctrine 2.0 (the upcoming version of Doctrine) support for plain vanilla value objects and for AMF remoting is planned and this trick/hack will not be needed. This is actually the reason why I didn’t bother to write my own hydration method. I’m planning to do a test run with the nightly builds soon.

[Top]

Creating the StudentsService service

It is time to move on and create another service for the students and marks tables. Create a file inside of doctrine_students/services/ folder named StudentsService.php.

Here is a blue print of the StudentsService class:

<?php

require_once(dirname(__FILE__) . '/../bootstrap.php');

require_once(dirname(__FILE__) . '/../vo/Country.php');

require_once(dirname(__FILE__) . '/../vo/Course.php');

$service = new StudentsService();

print_r($service->getAll());

class StudentsService {

    public function getAll() {

    }

    public function save($record) {

    }

    public function delete($record) {

    }

}

Let’s start by filling in the getAll() method. It will use the DQL feature to retrieve not only all the students, but also the country set for each student and all the marks he has (at this point you need to have some data in the students and marks tables):

public function getAll() {

    $q = Doctrine_Query::create()

                ->select('s.*, m.*, c.*')

                ->from('Students s')

                ->leftJoin('s.Marks m')

                ->leftJoin('s.Countries c')

                ->orderBy('s.last_name, s.first_name');

        $ret = $q->execute(null, Doctrine_Core::HYDRATE_ARRAY);

        return $ret;

}

Save the file and run it in the browser. If you choose view source you should see an array of arrays (see Figure 7).

Notice that for each record from the students table I retrieve all the records from the marks table (student_id = id) and the country record  from the countries table (country_id = id). This works because Doctrine takes into account all the relations between the tables when it creates the models.

Because I defined a one-to-many relation between the countries and students tables (a country can be assigned to any number of students) and a many-to-many table (marks) between the students and courses tables (each student can have a mark for each course), Doctrine generated the model (schema.yml) and model classes to support this database schema. Indeed if you open the doctrine_students/schema.yml file and look at the Students entry you’ll see that it has defined two relations: Countries and Marks.

These two relations have the same name as the two fields you saw when you ran the StudentsService->getAll() method.

Next you’ll need to create two value objects (Student and Mark) to use with StudentsService. Add these two classes to the doctrine_students/vo/ folder:

<?php

//Stundent.php file

class Student {

    public $id;

    public $first_name;

    public $last_name;

public $registration;

    public $marks;

    public $countries;

}

<?php

//Mark.php file

class Mark {

    public $student_id;

    public $course_id;

    public $mark;

}

Don’t forget to include these two new classes in the StudentsService.php file.

Now I’ll change the getAll() method to transform the array I get from the Doctrine query into an array of value objects:

//StundentsService class definition

...

private $types = array (0 => 'Student', 'Countries' => 'Country', 'Marks' => 'Mark');

public function getAll() {

    $q = Doctrine_Query::create()

            ->select('s.*, m.*, c.*')

            ->from('Students s')

            ->leftJoin('s.Marks m')

            ->leftJoin('s.Countries c')

            ->orderBy('s.last_name, s.first_name');

        $ret = $q->execute(null, Doctrine_Core::HYDRATE_ARRAY);

        $ret = prepareForAMF($ret, $this->types);

        return $ret;

}

...

Note: The prepareForAMF function works recursively as long as you provide the right mapping between the keys of the arrays and the value objects it needs to create. This time I defined these mappings as a class variable ($types).

If you run the code again you should now see arrays of value objects: Student, Mark, and Country.

There’s something else I want to fix. The registration field from the students table has the Date type. But in the array returned by the getAll() method it is a String. I want to make sure that this field is actually an instance of the DateTime class. This will pay dividends later on when I retrieve these records in the Flex client, because it will receive value objects that have the Date type for the registration field instead of String.

The best place to do this transformation is probably inside the prepareForAMF() function. I added an optional third argument that is an array of the fields that have Date or DateTime type. So here is the modified function:

function prepareForAMF($data, $arrTypes, $arrDates=NULL) {

    if (count($data) == 0)

        return $data;

    $ret = array();

    $substract = false;

    if (!array_key_exists('0', $data)) {

        $data = array($data);

        $substract = true;

    }

    for ($i=0; $i<count($data); $i++) {

        $o = new $arrTypes[0]();

        foreach ($data[$i] as $property => $value) {

            $pproperty = strtolower($property);

            if (!property_exists($o, $pproperty)) {

                continue;

            }

            if (array_key_exists($property, $arrTypes)) {

                if ($value == NULL) {

                    $o->$pproperty = array();

                    continue;

                }

                $newArr = $arrTypes;

                $newArr[0] = $arrTypes[$property];

                $o->$pproperty = prepareForAMF($value, $newArr, $arrDates);

            } else {

                if ($arrDates && array_key_exists($pproperty, $arrDates)) {

                    $o->$pproperty = new DateTime($value);

                } else {

                    $o->$pproperty = $value;

                }

            }

        }

        $ret[] = $o;

    }

    if ($substract)

        $ret = $ret[0];

    return $ret;

}

Then I add a third argument when calling the prepareForAMF() function inside of getAll():

//StundentsService class definition

...

private $dates = array('registration' => 1);

public function getAll() {

    $q = Doctrine_Query::create()

            ->select('s.*, m.*, c.*')

            ->from('Students s')

            ->leftJoin('s.Marks m')

            ->leftJoin('s.Countries c')

            ->orderBy('s.last_name, s.first_name');

        $ret = $q->execute(null, Doctrine_Core::HYDRATE_ARRAY);

        $ret = prepareForAMF($ret, $this->types, $this->dates);

        return $ret;

}

...

[Top]

Handling Create, Update, and Delete with Doctrine

It is time to write the StudentsService methods for creating, updating, and deleting records. For this, you need to fill in the blanks for the other two methods  defined earlier: save() and delete(). Please notice:

• I want to use the save() method for both creating new records and updating existing ones.
• The save() method receives one argument: an instance of a Student value object. If you want to add marks for the student you have to have Mark objects stored in the mark property.
• The save() method will add or change the related records from the marks table for the current student .
• The delete() method deletes all the related records from the marks table first and then the student (it is transaction safe).

Here is the code for save():

public function save($record) {

        $record = makeArrayFromObject($record, $this->dates);

        //update an existent student

        if ($record['id'] > 0) {

            //retrieve the current student model

            $o = Doctrine_Query::create()

                ->select('*')

                ->from('Students')

                ->where('id = ?', $record['id'])

                ->fetchOne();

            if (!$o)

                return false; //exit if there is no student

            //loading relations

            $o->Marks;

            //clean up the array

            $record['Marks'] = $record['marks'];

            unset($record['marks']);

            if (array_key_exists('countries', $record)) {

                //set the country id

                $o->country_id = $record['countries'][0]['id'];

                unset($record['countries']);

            }

            //modify the existent student data 

            //using the data we have in $record 

            $o->synchronizeWithArray($record);

        //insert a new student

        } else {

            $o = new Students();

            //load the main properties from the $record

            $o->fromArray(cleanRefences($record, $this->types));

            //add marks records for the student if any

            if ($record['marks']) {

                foreach ($record['marks'] as $val) {

                    $t = new Marks();

                    $t->fromArray($val);

                    $o->Marks[] = $t;

                }

            }

            //setting student's country id

            if (array_key_exists('countries', $record) && count($record['countries']) > 0) {

                $o->country_id = $record['countries'][0]['id'];

            }

        }

        //persist the data model to the database

        $o->save();

        //loading Countries relations

            $o->Countries;

        $ret = prepareForAMF($o->toArray(), $this->types, $this->dates);

            return $ret;

    }

And here is the code for two functions I use in the save() method (I declared these functions in the bootstrap.php file):

function makeArrayFromObject($data, $arrDates=NULL)

{

    $data = (array)$data;

    foreach ($data as $k => $v) {

        if (is_array($v)) {

            $data[$k] = makeArrayFromObject($v, $arrDates);

        } else {

            if ($arrDates && array_key_exists($k, $arrDates)) {

                if ($v instanceof DateTime) {

                    $data[$k] = $v->format('Y-m-d');

                } else {

                    $data[$k] = $v->toString('Y-M-d');

                }

            } else if (is_object($v)) {

                $data[$k] = (array)$v;

            }

        }

    }

    return $data;

}

function cleanRefences($data, $references)

{

    foreach ($references as $key => $val) {

        if (array_key_exists($key, $data)) {

            $data[$key] = NULL;

        }

    }

    return $data;

}

There are comments in the code so it should be easy to read and understand. I’ll explain just the parts I think are important:

• First of all, as I said earlier, Doctrine 1.x doesn’t have support for plain vanilla value objects. This is why the first thing I do is to transform the Student value object into an associative array using the makeArrayFromObject() function.
• When I update an existing record I use DQL to create an instance of Students. Once I have the Students object for the given ID, I want to load all the related marks records (by calling $o->Marks). Next I use the synchronizeWithArray() method to apply the changes from the $record array to the existing data (basically synchronizeWithArray() receives an associative array similar in structure to the one you get when using the Array hydration method on the same object). Finally I set the country id, and once I call the save() method on the Students object ($o->save()) the data are persisted.
• When I add a new record, I instantiate a Students object and then I use the fromArray() method to load the data from the $record array. However I found a glitch: for some reason it doesn’t work with the relations (in my case it didn’t save the related records to the marks table). So the workaround I found is to use the fromArray() method to load only the properties stored in the same table (students). This is why I clean the array from all the relations (Marks and Countries) using a call to the cleanReferences() function. I add the Marks objects manually using a for() loop.
• When adding marks records, it is interesting to note that Doctrine takes care of all the plumbing work for me. Suppose you add a new student and at the same time two marks: (course_id:1, mark:10) and (course_id:3, mark:9). The marks table has a third field student_id. When you call the save() method on the Students object, Doctrine will insert a new record in the students table, it will retrieve the id and then fill in the missing student_id for the two Mark records and then insert these two records.

The code for the delete() operation is much simpler. I use DQL to first delete all the related records from the marks table and then I delete the student record using an instance of Students. I make use of Doctrine support for transactions to keep the data consistent.

//StudentsService class definition

...

public function delete($record) {

        $record = makeArrayFromObject($record, $this->dates);

        //delete all related records from marks table

        $q = Doctrine_Query::create()

                ->delete('Marks')

                ->where('student_id = ?', $record['id']);

            //start transaction        

            $q->getConnection()->beginTransaction();

            $q->execute();

        $o = new Students();

        $o->assignIdentifier($record['id']);

        $o->delete();

        $q->getConnection()->commit(); //commit transaction

        $ret = prepareForAMF($o->toArray(), $this->types, $this->dates);

            return $ret;

    }

...

You now have all the code in place. If you want to verify it you can add testing code (the lines below) in the StudentsService.php file. Then run the file in the browser and then check the database:

$service = new StudentsService();

$c = new Country();

$c->id = 1;

$m1 = new Mark();

$m1->course_id = 3;

$m1->mark = 7;

$m2 = new Mark();

$m2->course_id = 4;

$m2->mark = 8;

$s = new Student();

$s->first_name = 'Michael';

$s->last_name = 'Doherty';

$s->registration = new DateTime('2010-03-14');

$s->countries = $c;

$s->marks = array($m1, $m2);

print_r($service->save($s));

Before moving on, don’t forget to comment (or delete) all the code you added in the service classes for testing.

[Top]

Installing the Zend Framework

The next task I have to complete on the PHP side is to enable support for remoting in PHP. I chose to do so by using the Zend Framework. You can use AMFPHP, WebORB for PHP, or SabreAMF as well.

Download and unzip the framework somewhere on your disk. Then use the php.ini file to include the framework:

include_path = ".:/Applications/MAMP/bin/php5/lib/php:/Applications/MAMP/zend_framework/library "

Save the file and restart the server. If you don’t have access to the php.ini you probably have to copy the whole framework under your web root, though this is not recommended for production.

[Top]

Setting up the gateway file

The last step I have to complete on the PHP side before moving to Flex is to create the gateway file. This file will represent the end point for all the remoting calls from the Flex application. It will configure and start the Zend AMF server.

Create a new file called gateway.php inside of doctrine_students folder and then add this code:

<?php

require_once('Zend/Amf/Server.php');

//create an instance of Zend AMF server

$server = new Zend_Amf_Server();

//adding the services folder in order to expose

//CatalogService and StudentsService

$server->addDirectory(dirname(__FILE__) . '/services/');

//Mapping the ActionScript VO to the PHP VO

//you don't have to add the package name

$server->setClassMap("Country", "Country");

$server->setClassMap("Course", "Course");

$server->setClassMap("Mark", "Mark");

$server->setClassMap("Student", "Student");

$server->setProduction(false);

echo($server -> handle());

Save the file and run it in the browser. You should either see the message “Zend Amf Endpoint” or a save dialog.

[Top]

Creating the Flex front-end

With all the PHP code in place, it is time to create the Flex front-end. From a workflow perspective you have two options:

• You can create a separate Flex project and have two projects in place: one for Flex and one for PHP.
• You can add Flex nature to the PHP project and use the same project for both Flex and PHP.

I usually prefer the second approach because I work on both Flex and PHP code and it is simple to debug them together.

To add Flex nature to the students project, right-click on the project name in Eclipse, and select Add/Change Project Type > Add Flex Project Type. When the wizard opens, select PHP as the application server type and click Next. Fill in the path to the web server root and URL to reach the root, then click Validate Configuration and then Finish. You might see this error in the Problems view: “Cannot create HTML wrapper. Right-click here to recreate folder html-template.” Just right-click on it and choose Recreate Folder HTML-template.

This wizard will create an MXML file named students.mxml as well. Open this file if you haven’t already and add the following code inside the <fx:Declarations> tag:

<s:RemoteObject id="catalogService" source="CatalogService" destination="zend"

                endpoint="../doctrine_students/gateway.php"

                result="onResult(event)" fault="onFault(event)">

    <s:method name="getCourses" />

    <s:method name="getCountries" />

</s:RemoteObject>

<s:RemoteObject id="studentsService" source="StudentsService" destination="zend"

                endpoint="../doctrine_students/gateway.php"

                result="onResult(event)" fault="onFault(event)">

    <s:method name="getAll" />

    <s:method name="save" />

    <s:method name="delete" />

</s:RemoteObject>

The code defines two remoteObjects, one for each service on the PHP side: CatalogService and StudentsService. I added the methods for clarity, although this is not mandatory. Note that the endpoint attribute points to the gateway.php file  created earlier.

The next step is to define the onResult and onFault event listeners. Add this code above or below the <fx:Declaration> tag:

<fx:Script>

    <![CDATA[

        import mx.rpc.events.FaultEvent;

        import mx.rpc.events.ResultEvent;

        private function onResult(e:ResultEvent):void {

        }

        private function onFault(e:FaultEvent):void {

        }

    ]]>

To test the code you’ll need to add a button and call one of the service’s methods on click. Next, add two breakpoints on the first line where each event listener is defined and then run the project in debug mode.

"catalogService.getCourses()"/>

After the page loads, click the button and in Eclipse you should see the Flex debugger stopped (see Figure 8).

[Top]

Creating the ActionScript value objects

When using remoting it is usually a good idea to create value objects on the Flex side that correspond to the value objects you have on the server side. In my case I need to create four value objects: Student, Mark, Course, and Country. I place all these classes in the org.corlan.vo package.

The code is here:

package org.corlan.vo {

    [Bindable]

    [RemoteClass(alias="Country")]

    public class Country {

        public var id:int;

        public var name:String;

    }

}

package org.corlan.vo {

    [Bindable]

    [RemoteClass(alias="Course")]

    public class Course {

        public var id:int;

        public var name:String;

    }

}

package org.corlan.vo {

    [Bindable]

    [RemoteClass(alias="Mark")]

    public class Mark {

        public var student_id:int;

        public var course_id:int;

        public var mark:Number;

    }

}

package org.corlan.vo {

    [Bindable]

    [RemoteClass(alias="Student")]

    public class Student {

        public var id:int;

        public var first_name:String;

        public var last_name:String;

        public var registration:Date;

        public var countries:Country;

        private var _marks:Array;

        public function get marks():Array {

            return _marks;

        }

        public function set marks(value:Array):void {

            for (var i:int=0; i

                value[i] = value[i] as Mark;

            }

            _marks = value;

        }

    }

}

There is nothing special to these value object classes. I’m using the Bindable metadata to make each property bindable and I use the RemoteClass metadata to tell AMF which is the corresponding class on the server side. On the PHP side I have the mapping defined inside of the gateway.php file using the setClassMap() method from AMF server - $server->setClassMap("Country", "Country");.

For the Student value object I use the getter/setter to cast the array of objects received from the server to an array of Mark value objects.

Before testing the code you need to make sure that these four value object classes are included in the compiled SWF. You can simply add these lines in the students.mxml file:

import org.corlan.vo.*;

static public var clz:Array = [Country, Course, Mark, Student];

If you run the project and call the studentsService.getAll() method when clicking on the button, you should see the value objects in the Flex debugger (see Figure 9).

[Top]

Creating the UI

Now you can focus on the UI of this application. It will be a simple UI with a data grid for displaying all the students (see Figure 10). When a student is selected from the data grid, the form on the right is populated and you can use it to change details for the current student. If you want to delete a student, just select a row and click Delete. If you want to add a new record, click New and then fill in the form.

I have a function that is used for creating the text in the courses column, and a bunch of arrays I’m using to store the data models (courses, countries, and students).

Here is the code for the application:

"1.0" encoding="utf-8"?>

"http://ns.adobe.com/mxml/2009"

               xmlns:s="library://ns.adobe.com/flex/spark"

               xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600" creationComplete="init()" xmlns:vo="org.corlan.vo.*">

        

            [Bindable]
            private var arrStudents:ArrayCollection;
            [Bindable]
            private var arrCourses:ArrayCollection;
            [Bindable]
            private var arrCountries:ArrayCollection;

            private var coursesHash:Object;
            private var marks:Array;

            private function init():void {
                catalogService.getCourses();
                catalogService.getCountries();
            }

            private function getStudents():void {
                studentsService.getAll();
            }

            private function onStudents(e:ResultEvent):void {
                arrStudents = new ArrayCollection(e.result as Array);
            }

            private function onCourses(e:ResultEvent):void {
                arrCourses = new ArrayCollection(e.result as Array);
                //save the courses into a hashmap
                var l:int = arrCourses.length;
                coursesHash = new Object();
                marks = new Array();
                var c:Course;
                for (var i:int = 0; i
                    c = (arrCourses[i] as Course);
                    coursesHash

[/c]

 = c.name;
                    marks.push({course_id : c.id, mark : 0, name : c.name});
                }
                dgMarks.dataProvider = marks;
            }

            private function onCountries(e:ResultEvent):void {
                arrCountries = new ArrayCollection(e.result as Array);
            }

            private function onFault(e:FaultEvent):void {
                Alert.show(e.fault.faultDetail, "Error!");
            }

            private function onSelection(e:ListEvent):void {
                student = e.itemRenderer.data as Student;
                if (student.countries) {
                    var l:int = arrCountries.length;
                    for (var i:int = 0; i<l; i++) {
                        if (arrCountries[i].id == student.countries.id) {
                            country.selectedIndex = i;
                            break;
                        }
                    }
                }

                if (student.marks && student.marks.length > 0) {
                    var k:int = marks.length;
                    var o:Object;
                    for (var j:int = 0; j<k; j++) {
                        o = marks[j];
                        o["mark"] = 0;
                        for (var jj:int = 0; jj < student.marks.length; jj++) {
                            if (student.marks[jj].course_id == o["course_id"]) {
                                o["mark"] = student.marks[jj].mark;
                                break;
                            }
                        }
                    }
                    dgMarks.dataProvider = marks;
                }
            }

            private function customLabel(data:Object, column:DataGridColumn):String {
                var arr:Array = new Array();
                var c:int = (data as Student).marks.length;
                var mark:Mark;
                for (var i:int = 0; i<c; i++) {
                    mark = (data as Student).marks[i];
                    arr.push(coursesHash[mark.course_id]);
                }
                return arr.join(", ");
            }

            private function saveStudent():void {
                //set the marks
                var l:int = marks.length;
                var m:Mark;
                student.marks = new Array();
                for (var i:int = 0; i<l; i++) {
                    if (marks[i]["mark"] > 0) {
                        m = new Mark();
                        m.course_id = marks[i]["course_id"];
                        m.mark = marks[i]["mark"];
                        if (student.id > 0)
                            m.student_id = student.id;
                        student.marks.push(m);
                    }
                }
                //set the country
                student.countries = country.selectedItem as Country;
                //set the names and registration date
                student.first_name = first.text;
                student.last_name = last.text;
                student.registration = registration.selectedDate;
                studentsService.save(student);
            }

            private function deleteStudent():void {
                if (!student || !student.id)
                    return;
                var o:AbstractOperation = studentsService.getOperation("delete");
                o.send(student);
            }
        ]]>
    </fx:Script>
    <fx:Declarations>
        <s:RemoteObject id="catalogService" source="CatalogService" destination="zend"
                        endpoint="../doctrine_students/gateway.php" fault="onFault(event)">
            <s:method name="getCourses" result="onCourses(event)"/>
            <s:method name="getCountries" result="onCountries(event)"/>
        </s:RemoteObject>

        <s:RemoteObject id="studentsService" source="StudentsService" destination="zend"
                        endpoint="../doctrine_students/gateway.php" fault="onFault(event)">
            <s:method name="getAll" result="onStudents(event)"/>
            <s:method name="save" result="getStudents()"/>
            <s:method name="delete" result="getStudents()" />
        </s:RemoteObject>
        <vo:Student id="student"/>
    </fx:Declarations>

    <mx:DataGrid id="dgStudents" dataProvider="{arrStudents}" x="13" y="14" itemClick="onSelection(event)">
        <mx:columns>
            <mx:DataGridColumn headerText="First" dataField="first_name"/>
            <mx:DataGridColumn headerText="Last" dataField="last_name"/>
            <mx:DataGridColumn headerText="Country" dataField="countries.name"/>
            <mx:DataGridColumn headerText="Courses" labelFunction="customLabel" width="200"/>
        </mx:columns>
    </mx:DataGrid>

    <s:Button click="getStudents()" label="Get Students" x="13" y="200"/>
    <s:Button x="112" y="200" label="New" click="student = new Student();"/>
    <s:Button x="190" y="200" label="Delete" click="deleteStudent()"/>

    <mx:Form x="510" y="0">
        <mx:FormItem label="First:">
            <s:TextInput id="first" text="{student.first_name}"/>
        </mx:FormItem>
        <mx:FormItem label="Last:">
            <s:TextInput id="last" text="{student.last_name}"/>
        </mx:FormItem>
        <mx:FormItem label="Registration:">
            <mx:DateField id="registration" selectedDate="{student.registration}"/>
        </mx:FormItem>
        <mx:FormItem label="Country:">
            <s:List id="country" dataProvider="{arrCountries}" labelField="name" height="70"></s:List>
        </mx:FormItem>
        <mx:FormItem label="Marks:">
            <mx:DataGrid id="dgMarks" editable="true">
                <mx:columns>
                    <mx:DataGridColumn headerText="Course" dataField="name" editable="false"/>
                    <mx:DataGridColumn headerText="Mark" dataField="mark" editable="true"/>
                </mx:columns>
            </mx:DataGrid>
        </mx:FormItem>
        <mx:FormItem>
            <s:Button label="Save" click="saveStudent()"/>
        </mx:FormItem>
    </mx:Form>

</s:Application>

[Top]

Getting the source code

If you want to have a look at the project files here are the links:

• The doctrine_students folder is here. It includes the Doctrine framework, the gateway.php and bootstrap.php files, the models, services, and value object classes.
• From here you can download the source folder of the Flex project (you need the Flex 4 SDK to compile it).
• Use this script to create the database and populate it with some data.
• You can find the MySQL Workbench model file here.

[Top]

Conclusions

In my experience, a software application is pretty much like a living thing: it grows and changes over time. Having some help along the way to make these changes smoother, reduce hand-coding, and minimize the potential for injecting bugs can make a big difference.

I think using an ORM framework on the server and letting this framework do the heavy lifting (generating the models based on the database structure, escaping the values to protect against SQL injection, making it easy to create a complex domain model, and making it easy to create CRUD services) is something that you may want to consider for your next project. These capabilities are especially helpful in the world of rich Internet applications where an important part of the business application stays on the client’s machine.

The only drawback I see with the current version of Doctrine (1.x) is that it needs some boiler plate code in order to make it possible to work with remoting and Flex. You can tweak the framework even more to make it generate the value objects as well. It seems the next version of Doctrine will make this integration much easier, and I plan to check this out soon :).

Until next time, please drop a comment and share your experience with PHP ORMs and using them with Flex.

[Top]

I’ve just published a white paper on debugging Flex and PHP projects using Flash Builder 4, Eclipse PDT, and XDebug. You can read the article here.

In case you want to watch the webinar I did on the same subject today, you can go here. Thank you to all the people who joined my webinar!

PS. It seems we’ve come a long way when it comes to writing Flex applications. Out of 250+ registered people, only 60 decided to drop by. This is really good news, soon there will be no more bugs in our software :D

We’ve just launched Flash Builder 4, our latest IDE for building RIAs with Flex and ActionScript. If you use PHP on the server side, you may want to join my webinar on Debugging Flex and PHP projects.

I will talk about the new features of Flash Builder 4 that can help you while debugging and I will show how you can use Flash Builder 4 with Eclipse PDT and XDebug. The webinar will be this Wednesday (March 24th), 11AM Central European Time. You can register here.

As you know, one of my focuses as a Platform evangelist is Flex and PHP integration. Thus you can imagine I spend quite a lot of time doing Flex and PHP projects or research around these technologies. Lately I’ve been working on workflows for PHP and Flex (tooling, debugging, libraries) in light of the new tools (or new versions) we have been developing at Adobe. While some of these findings will see the light as articles, others are more intended as suggestions or feature request for upcoming versions of Flash Builder.

I’m really curious to find out:

• What tools are you using?
• What do you use for debugging?
• What frameworks (AMFPHP, Zend Framework, Doctrine etc) do you use when working on Flex and PHP projects?
• And the most important question: What features do you think Flash Builder needs in order to make you a happier/richer developer?

Please take some time and drop a comment with your thoughts around these questions.

And because I understand it takes some time to answer these questions, I want to give away three Flash Builder 4 licenses. I will choose randomly three lucky people from those who take the survey. The winners will be announced at the end of March, however you’ll get the licenses once we release Flash Builder 4 (now it is in Beta 2). Make sure you fill in your real name and a valid email address.

LATER EDIT: The winners of this raffle are: Mario Kralj, chandra shekhar pant, and Ben Dalton! Congratulations and pretty soon you’ receive the license.

On December 2nd, together with Roy Ganor from Zend, I will host an e-seminar about PHP and the Flash Platform. We will show you how you can create a Rich Internet Application using the Flex framework, Illustrator, Flash Catalyst, and Flash Builder 4. Then we will show you how to connect the Flex application to a PHP backend and how easy is to debug the PHP and Flex code using Zend Studio 7.1 and Flash Builder 4.

You can register for free here. The webinar will start at 6:00 PM Central European Time (9:00AM Pacific Standard Time) on December 2nd.

LATER UPDATE:

You can download the slides from here, and next week the recording will be available you can watch the recording over here (you need to have a Zend account).

Last week I visited Zend headquarters, and I had an interesting talk over there. One effect of this meeting is this: we will start to do webinars together with Zend.

If you want to find more about Zend Studio and other products related to PHP from Zend, or learn more about the integration between the Flash Platform and PHP (Flash Catalyst, Flash Builder, Flex framework) you shouldn’t miss this opportunity. I know that webinars don’t offer the same experience as in-person events. On the other hand, you can attend them from the comfort of your own home, there is no traveling involved and no need to convince your boss to let you attend the event.

We haven’t set the first event date yet, but it should be in the first week of December, and probably it will be in the evening (Central European Time).

Keep an eye on my blog for the exact date and time.

Finally, I managed to finish an article that introduces Flex to PHP developers comparing features from both worlds (when it makes sense). I’ve been working on this subject from the beginning of this year. Thus I am so happy that I feel I should go out and smoke a fine Cuban cigar :)

While working on this article I realized two things:

1. Writing books it is not easy. My work doesn’t compare with a book at all, but still the amount of work was huge. Now, I have an idea about what it means to work on a book.
2. Learning a client-side technology coming from the server-side world will never be an easy and straightforward task. You have to adapt to a new world and adopt a different mindset. But then again, with big efforts usually come big rewards! And from my experience, when I learn something new I can always apply some of this knowledge to the concepts I’ve already known.

Enjoy the article and let me know what do you think!

On June 1st we launched the public beta for Flash Builder 4, the newest iteration of our Eclipse-based IDE for RIAs, formerly known as Flex Builder 3. While you can find both evolutionary and revolutionary features in it, in this article I will touch on the data features and Flex – PHP integration features of Flash Builder 4.

In this article, I will show you how can you use a PHP class that manages a MySQL table (offering CRUD operations) in a Flex project. I will build the Flex project and I rely on Flash Builder 4 to set up the Zend Framework for me(because I want to use remoting as a way to talk with the PHP server). After this I will use the new wizard from Flash Builder 4 that introspects a PHP class and creates the ActionScript code to consume that PHP class.

In the end I should be able to have a simple Flex app that lets me see the data records, edit them, and add a new item. For some of the features I’ll have to write code, for others Flash Builder will generate the code. All in all, I think the application can be created in less than 30 minutes.

PHP code

I have two PHP classes that I want to reuse with my Flex application. One class is a data object that acts asa wrapper for one row from my database (MySQL). Here is the structure of the table:

authors
——————————
id_aut – primary key
fname_aut string
lname_aut string

The PHP data object, called VOAuthor, looks like this:

   1: class VOAuthor {

   2:    

   3:     public $id_aut;

   4:     public $fname_aut;

   5:     public $lname_aut;

   6: }

The second class, called Authors, is the class that manages the table, offering CRUD operations. The code is very straight forward, I don’t use any database abstraction layer. I have three methods one each for reading, deleting, and updating/inserting a record. I use the data object, VOAuthor, within these methods. This is the code:

   1: require_once 'VOAuthor.php';

   2:  

   3:  

   4: //connection info

   5: define("DATABASE_SERVER", "localhost");

   6: define("DATABASE_USERNAME", "mihai");

   7: define("DATABASE_PASSWORD", "mihai");

   8: define("DATABASE_NAME", "flex360");

   9:  

  10: //$o = new MyService();

  11: //print_r($o->getData());

  12:  

  13: class Authors {

  14:     

  15:     /**

  16:      * Retrieve all the records from the table

  17:      * @return an array of VOAuthor

  18:      */

  19:     public function getData() {

  20:         //connect to the database.

  21:         //we could have used an abstracting layer for connecting to the database.

  22:         //for the sake of simplicity, I choose not to.

  23:         $mysql = mysql_connect(DATABASE_SERVER, DATABASE_USERNAME, DATABASE_PASSWORD);

  24:         mysql_select_db(DATABASE_NAME);

  25:         //retrieve all rows

  26:         $query = "SELECT id_aut, fname_aut, lname_aut FROM authors_aut ORDER BY fname_aut";

  27:         $result = mysql_query($query);

  28:         //throw (new Zend_Amf_Exception('error', 11));

  29:         $ret = array();

  30:         while ($row = mysql_fetch_object($result, "VOAuthor")) {

  31:             $ret[] = $row;

  32:         }

  33:         mysql_free_result($result); 

  34:         return $ret;

  35:     }

  36:         /**

  37:      * Update one item in the table

  38:      * @param VOAuthor to be updated 

  39:      * @return NULL

  40:      */

  41:     public function saveData($author) {

  42:         if ($author == NULL)

  43:             return NULL;

  44:         //logMe($author);

  45:         //connect to the database.

  46:         $mysql = mysql_connect(DATABASE_SERVER, DATABASE_USERNAME, DATABASE_PASSWORD);

  47:         mysql_select_db(DATABASE_NAME);

  48:         if ($author->id_aut > 0) {

  49:             //save changes

  50:             $query = "UPDATE authors_aut SET fname_aut='".$author->fname_aut."', lname_aut='".$author->lname_aut."' WHERE id_aut=".  $author->id_aut;

  51:         } else {

  52:             //add new record

  53:             $query = "INSERT INTO authors_aut (fname_aut, lname_aut) VALUES ('".$author->fname_aut."', '".$author->lname_aut."')";

  54:         }

  55:         $result = mysql_query($query);

  56:         return NULL;

  57:     }

  58:     

  59:     public function deleteData($author) {

  60:         if ($author == NULL)

  61:             return NULL;

  62:         

  63:         //connect to the database.

  64:         $mysql = mysql_connect(DATABASE_SERVER, DATABASE_USERNAME, DATABASE_PASSWORD);

  65:         mysql_select_db(DATABASE_NAME);

  66:         //add new record

  67:         $query = "DELETE FROM authors_aut WHERE id_aut = ".$author->id_aut;

  68:         $result = mysql_query($query);

  69:         return NULL;

  70:     }

  71:     

  72: }

These two scripts sit inside of a folder called “remoting” in the root of the Apache web server document root folder.

Creating the Flex project and the UI of the app

I have the PHP files in place; now it’s time to create the Flex application. First, I need to create a new Flex project. Having opened the Flash Builder 4, I use the “New Flex Project” wizard to create a new Flex project called FlexPHPAMF. Make sure that in the wizard you choose PHP as the server technology, and you give the correct information for the document root of the web server (absolute path and URL).

Now let’s create the UI of the application. To do this, I chose to go in design mode where I added two buttons and a data grid to the stage. One button is labeled “Get Data” and the other one “Save Data”.

Using the data service panel

Finally, I am ready to use the new data wizards.At the bottom of Flash Builder, there is a view called “Data/Services”. Click on “Connect to Data/Service” link. A wizard starts, and you can select the type of the data service.

Because I want to use the PHP classes I have, I choose PHP and I click “Next”.

On this page, you can select to either reuse an existing service from the server, or to let the wizard create a stub for you. Because I have the service, I want to use the Import PHP class option. Flash Builder introspects the service in order to detect the supported operations (in this case, because I am using remoting, it detects the public methods and the return type). But to do so, it needs to install the Zend Framework to your web server.

What is very cool is that you don’t have to worry about the steps needed to install Zend Framework. Flash Builder will do it for you automatically.

After the Zend Framework is installed, on the last page of the wizard you’ll see the available methods. Click Finish.

Now, in the Data/Services view you should have a tree, with the root node named Authors. This is the name of the PHP class that you want to use in Flex. Under this node you have Data Types, and the three methods: deleteData(), getData(), saveData().

At the same time if you take a look at the project structure in the Package explorer, you’ll notice that new packages and files were created.

There is a new package called services.authors, and here you’ll find the service class that you’ll use to connect to the PHP class (Authors.as). This class actually extends a base class that implements all the logic using RemoteObject. The reason for this approach is that when you need to do your customization, you’ll do it in the Authors class. If you decide to use Flash Builder to regenerate the code for the same service (maybe as a result of a change on the server side), this operation will not over write your custom code.

The same goes for the data object (or value object). Flash Builder generated the ActionScript value object to match the PHP class VOAuthor. But again, you might want to do some customizations, and you can do it by touching VOAuthor that extends _Super_VOAuthor. All the generated code stays in the _Super_VOAuthor.

And finally, you’ll find a folder called services that gives you quick access to the Authors.php class.

It is time to fill the data grid with the data from the server. To do so, first you need to make sure that the return type for the getData() operation is an array of VOAuthor objects. If you right click on the name of the operation in the Data/Services view and choose Configure Return Type, you have a way to specify the array of VOAuthor:

To bind the data grid to the result of the getData() operation you have to go into design mode, and then drag and drop the getData() (from the Data/Services view) to the data grid.

If you switch to code view, you’ll see that some ActionScript code was added to the flexPHPAMF.mxml. What you want to do is to grab the line from the function and create a new function that will be called when you click the “Get Data” button and paste the code inside of it. My code looks like this:

   1: protected function getData():void

   2: {

   3:    getDataResult.token = authors.getData();

   4: }

   5: [...]

   6:  

   7: <s:Button x="43" y="220" label="Get Data" click="getData()"/>

The wizard altered the data grid itself, you have the name of the table fields as labels, and the data provider of the data grid is set to the lastResult of the getDataResult object (this object was added to your code by the wizard, in order to help you manage the results of the authors service).

If you run the application and press the “Get Data” button, you should see the data.

Adding editing capabilities

The final part of this tutorial is adding the editing capabilities. I want to be able to edit an existing record using the data grid itself, and I want to have a form and a new button. First go back into design mode, drag and drop an new button on the stage, and change the label to “New”. Then, you’ll use another wizard to generate the form for editing. To do so, you select from the Data/Services view the Data Types node, expand it, and select the VOAuthor node. Right click it and select Generate Form. In the wizard choose “Make form editable” and click Next.

In the second page of the wizard deselect the “id_aut” property. This value will be auto-inserted by the database itself. Click Finish.

After the form is generated, you want to grab the form and position it maybe below the buttons. Also, you may want to change the labels. Finally add a new button in the form and label it “Add”.

Switch back to code view. Now, you need to make some changes. First of all (I think it is a bug), the text fields are not editable (they are Text instead of TextInput). So change the type to TextInput to make them editable. Next, give an ID to the Form itself. I want to have the form invisible when the application is loaded, and only make it visible when the users clicks “New”. For that you set the visible property on the form to false, and you add some code to the New button. Here is my code:

   1: <s:Button x="224" y="220" label="New" click="myForm.visible = true"/>

   2: <mx:Form x="46" y="277" id="myForm" visible="false">

   3:         <mx:FormItem label="First Name:">

   4:             <mx:TextInput id="fname" text=""/>

   5:         </mx:FormItem>

   6:         <mx:FormItem label="Last Name:">

   7:             <mx:TextInput id="lname" text=""/>

   8:         </mx:FormItem>

   9:         <mx:FormItem>

  10:             <s:Button label="Add"/>

  11:         </mx:FormItem>

  12: </mx:Form>

And if you look in the code, you’ll notice a new object was created:

   1: <authors:VOAuthor id="vOAuthor"/>

You’ll use this instance of the value object VOAuthor to send the new item to the server (remember, the PHP saveData() method expects a single argument of type VOAuthor).

To do so, you need to create a binding between the two text fields from the form and the properties fname_aut and lname_aut of the VOAuthor.

   1: <fx:Binding destination="vOAuthor.fname_aut" source="fname.text"/>

   2: <fx:Binding destination="vOAuthor.lname_aut" source="lname.text"/>

The last missing piece is the actual call to the saveData() method. This is very simple;on the click event of the “Save” button you add the call to the authors object getData() method, passing the local instance of VOAuthor (vOAuthor) as the argument:

   1: <s:Button label="Add" click="authors.saveData(vOAuthor)"/>

You can add a new record now. What about editing an existing one? For this we will need a little bit more code. First, you want to register a listener on the data grid in order to know when something was edited (if you set the property editable to true on the data grid, then you can edit information inline). The event you are looking for is itemEditEnd:

   1: <mx:DataGrid x="44" y="37" id="dataGrid" dataProvider="{getDataResult.lastResult}" 

   2:         itemEditEnd="dataEdited(event)" editable="true">

Now,let’s define the listener, dataEdited(). Add the following code in the script section of the page:

   1: private function dataEdited(event: DataGridEvent):void 

   2: {

   3:      vOAuthor = event.itemRenderer.data as VOAuthor;

   4: }

This code uses the instance of the value object VOAuthor to store the data used by the edited row.

The last two things you have to do is to create a function called saveData() that is called when the user clicks the “Save Data” button, and to add initialization code for the vOAuthor object when the users clicks the “New” button (this way you avoid updating an item instead of adding a new one if you first edit a row and then add one):

   1: private function saveData():void {

   2:    if (vOAuthor != null)

   3:       authors.saveData(vOAuthor);

   4: }

   1: <s:Button x="224" y="220" label="New" 

   2:     click="myForm.visible = true; vOAuthor = new VOAuthor()"/>

The final code of the MXML file should look like this:

   1: <?xml version="1.0" encoding="utf-8"?>

   2: <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:mx="library://ns.adobe.com/flex/halo" minWidth="1024" minHeight="768" xmlns:authors="services.authors.*">

   3:     <fx:Script>

   4:         <![CDATA[

   5:             import mx.events.DataGridEvent;

   6:             import services.authors.VOAuthor;

   7:             import mx.events.FlexEvent;

   8:             import mx.controls.Alert;

   9:             

  10:             protected function getData():void

  11:             {

  12:                 getDataResult.token = authors.getData();

  13:             }

  14:             

  15:             private function dataEdited(event: DataGridEvent):void 

  16:             {

  17:                 vOAuthor = event.itemRenderer.data as VOAuthor;

  18:             }

  19:             

  20:             private function saveData():void {