Getting Started

This is a step-by-step guide to setting up a simple Flextrine project. Topics touched on in this document will be expanded upon in later documentation, but this a good place to get an idea of the fundamentals of Flextrine and how to apply them in your projects.

These instructions refer to Flextrine 0.6.1 and later.

1. Setting up the server

The first thing to do when setting up a new Flextrine project is to configure the server-side component. To do this copy flextrine/web/flextrineproject to a web accessible directory and rename it, for example, to myflextrineproject. For the purposes of this tutorial we will assume that the folder is accessible via http://localhost/myflextrineproject.

If you haven't added flextrine/web/lib to your PHP include path, either because you do not have permissions or you don't want to edit your php.ini, you can set this directory on a project basis. Open up myflextrineproject/config.php, uncomment the $flextrineIncludePath decleration and change the path to wherever you have placed flextrine/web/lib. For example, if the Flextrine lib folder was at C:/Projects/Flextrine/web/lib the flextrineIncludePath in config.php might read:

/**
 * If you don't want to add the Flextrine lib folder to your include path in php.ini set it here
 */
$flextrineIncludePath = "C:/Projects/Flextrine/web/lib";

If the directory is already in your include path you can leave this line commented out.

You also need to install Doctrine 2 by downloading the package and copying the files into a directory in your include path. An easy option is to unpack the Doctrine lib folder into the Flextrine lib folder so that you have Flextrine/web/lib/Doctrine/ORM, Flextrine/web/lib/Doctrine/DBAL and Flextrine/web/lib/Doctrine/Common.

Note that Doctrine 2 is still under development and there may be issues in the packaged version that limit Flextrine's functionality. Cloning Doctrine 2 from git will allow you to track the most up to date version.

2. Configure your database

Create a new database for your Flextrine project, configure a user and password with access to the database and then open myflextrineproject/config.php and edit the $connectionOptions variable accordingly.

For example, if you had created a MySQL database called myflextrinedb, with user myflextrineuser and password password the options would read:

$connectionOptions = array(
   'dbname' => 'myflextrinedb',
   'user' => 'myflextrineuser',
   'password' => 'password',
   'host' => 'localhost',
   'driver' => 'pdo_mysql',
);

3. Create some persistent entities

You now need to define your persistent entities. These are the objects that you want to enable for object-database mapping. You define these objects in PHP then use the Flextrine Manager to update the schema and generate the matching AS3 classes.

In our example we are going to create a Doctor entity with an id and a name, and we'll put this object in the vo package. This means that when we come to use Doctor in Flex we will import it using:

import vo.Doctor;

Create a new folder in entities called vo, and then create Doctor.php within that new folder (so this new file will be located at entities/vo/Doctor.php). The class definition looks like this:

<?php
namespace vo;

/**
 * @Entity
 */

class Doctor {

    /** @Id @Column(type="integer") @GeneratedValue(strategy="IDENTITY") */
    public $id;
	
    /** @Column(length=100, type="string") */
    public $name;
	
}

?>

Check out the Entities section for detailed information on how to write Flextrine entities.

4. Generate the database schema and AS3 classes

We now need to use the Flextrine Manager to create our database tables and generate our AS3 classes. See Installing Flextrine Manager for instructions on how to setup the manager. Now open up the manager and in the FLEXTRINE PROJECT URL text box to the right enter the URL of our Flextrine server-side component; in this case http://localhost/myflextrineproject. Click Refresh and the manager should populate with information stating the name of the database and any installed entities - in our case vo/Doctor should show up as the only entity.

Click on Generate schema and in a few moments a message should pop up saying Schema generated successfully. Under the hood Flextrine (in fact Doctrine) has examined your entities and determined what kind of tables are required to store them. So for our Doctor the following SQL was actually executed.

CREATE TABLE doctor (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(100) NOT NULL,
  PRIMARY KEY (`id`)
);

Now click on Generate AS3 Classes and save the zip somewhere. This will have created a vo/DoctorEntityBase.as and a vo/Doctor.as file which effectively makes up an AS3 version of Doctor.php with a some extra magic to allow Flextrine to do its thing.

5. Create a Flex project

Create a new Flex project in your favourite Flex IDE and add the flextrine/src folder to your classpath. Now upzip the FlextrineAS3Classes.zip file generated by the manager into your project source directory (there should be a single vo directory containing a DoctorEntityBase.as and Doctor.as). The Flextrine database, server-side component and client libraries are now set up and ready to go!

There is one final proviso - if you are using Flex 3 you need to add the following to the additional compiler options:

-keep-as3-metadata += Id Association Entity

This step is not required for Flex 4.

6. Write some code!

Create an MXML file called FlextrineExample.mxml and set it to be the entry point to your project. In order to get things going we need to get the EntityManager (our central access point to Flextrine) and tell it the URL of our server-side component.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="creationComplete()">
	<mx:Script>
		<![CDATA[
			import org.davekeen.flextrine.orm.Configuration;
			import org.davekeen.flextrine.orm.EntityManager;
			import vo.Doctor;

			private var em:EntityManager;

			private function creationComplete():void {
				// Get the EntityManager and configure it to point at our server-side component
				em = EntityManager.getInstance();
				
				var configuration:Configuration = new Configuration();
				configuration.gateway = "http://localhost/myflextrineproject/gateway.php";
				
				em.setConfiguration(configuration);
				
				// Put your Flextrine code here!
			}
			
		]]>
	</mx:Script>
</mx:Application>

Now lets use Flextrine to create some new doctors. To tell Flextrine to create a new object in the database we use the persist method on EntityManager, passing the entity we want to persist as the parameter.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="creationComplete()">
	<mx:Script>
		<![CDATA[
			import org.davekeen.flextrine.orm.Configuration;
			import org.davekeen.flextrine.orm.EntityManager;
			import vo.Doctor;

			private var em:EntityManager;

			private function creationComplete():void {
				// Get the EntityManager and configure it to point at our server-side component
				em = EntityManager.getInstance();
				
				var configuration:Configuration = new Configuration();
				configuration.gateway = "http://localhost/myflextrineproject/gateway.php";
				
				em.setConfiguration(configuration);
				
				// Create some doctors
				var doctorRobert:Doctor = new Doctor();
				doctorRobert.name = "Doctor Robert";
				em.persist(doctorRobert);
				
				var doctorBorquin:Doctor = new Doctor();
				doctorBorquin.name = "Doctor Borquin";
				em.persist(doctorBorquin);
				
				em.flush();
			}
			
		]]>
	</mx:Script>
	
</mx:Application>

Notice that we call flush on EntityManager after persisting the two Doctors. Flextrine doesn't actually change the database until we call this method; instead it queues up all the things it needs to do until we call flush at which point it executes everything on the server. The doctor table in the database now contain two rows, one for Doctor Robert and another for Doctor Borquin.

This time lets retrieve the doctors in the database and show them in a DataGrid.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="creationComplete()">
	<mx:Script>
		<![CDATA[
			import org.davekeen.flextrine.orm.Configuration;
			import org.davekeen.flextrine.orm.EntityManager;
			import vo.Doctor;

			private var em:EntityManager;

			private function creationComplete():void {
				// Get the EntityManager and configure it to point at our server-side component
				em = EntityManager.getInstance();
				
				var configuration:Configuration = new Configuration();
				configuration.gateway = "http://localhost/myflextrineproject/gateway.php";
				
				em.setConfiguration(configuration);
				
				dataGrid.dataProvider = em.getRepository(Doctor).entities;
				em.getRepository(Doctor).loadAll();
			}
			
		]]>
	</mx:Script>
	
	<mx:DataGrid id="dataGrid" width="100%" height="100%">
                <mx:columns>
                        <mx:DataGridColumn dataField="name" />
                </mx:columns>
	</mx:DataGrid>
	
</mx:Application>

In this example we bind the dataProvider of the DataGrid to the entities in the Doctor EntityRepository. Check out the EntityRepository page for more details on this class, but very simply you can think of an EntityRepository as your local copy of the objects in the database. It starts out empty, but as you persist and load objects from the server the repositories fill up with objects. There is one EntityRepository for each entity - in this case we are binding to the entities in the Doctor repository. And since Flextrine respects databinding throughout its architecture any change in the entities of a repository will be instantly reflected in any components bound to it.

Furthermore once an entity is in an EntityRepository (either because it has been loaded or persisted) Flextrine will start watching that entity for changes, and if any of its properties change it will schedule that entity for an update on the next flush. This means that we can very simply add editing capability to our example.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="creationComplete()">
	<mx:Script>
		<![CDATA[
			import org.davekeen.flextrine.orm.Configuration;
			import org.davekeen.flextrine.orm.EntityManager;
			import vo.Doctor;
			
			private var em:EntityManager;
			
			private function creationComplete():void {
				// Get the EntityManager and configure it to point at our server-side component
				 em = EntityManager.getInstance();
				
				var configuration:Configuration = new Configuration();
				configuration.gateway = "http://localhost/myflextrineproject/gateway.php";
				
				em.setConfiguration(configuration);
				
				dataGrid.dataProvider = em.getRepository(Doctor).entities;
				em.getRepository(Doctor).loadAll();
			}
			
		]]>
	</mx:Script>
	
	<mx:DataGrid id="dataGrid" width="100%" height="100%" editable="true" valueCommit="em.flush()">
		<mx:columns>
			<mx:DataGridColumn dataField="name" />
		</mx:columns>
	</mx:DataGrid>
	
</mx:Application>

All we have done here is to set editable="true", and added an event handler that tells the EntityManager to flush when a row is changed. Flextrine and Flex databinding takes care of the rest, ensuring that any changes to a Doctor are queued up and written to the database as required.

Conclusion

As you can see it is quite simple to create powerful data driven applications with Flextrine. However, the full capabilities of Flextrine become apparent when you start using associations to link objects together. Read through the rest of the documentation for more details.