Propel

From the Propel project website: Propel is an Object Relational Mapping (ORM) framework for PHP5. It allows you to access your database using a set of objects, providing a simple API for storing and retrieving data.

Propel allows you, the web application developer, to work with databases in the same way you work with other classes and objects in PHP.

* You don't have to worry about database connections or writing SQL -- unless you want to.
* You never have to worry about escaping data or type-casting results.
* You define your database in a simple XML format (or tell Propel to build it from an existing database) and Propel will create database initialization files for your database and will generate static classes and objects that provide an OO interface to your database. (It can generate other useful things based on the datamodel too!)
* Propel builds classes which are aware of the structure of your database so there's no performance lost to initialization or to on-the-fly database metadata queries.

Most of you will agree that writing database queries and access code is one of the most tedious jobs in application development. Propel does an extremely good job at simplifying this work for the reasons mentioned above.

Mapping objects

The classes built by Propel use explicit getters and setters. That means they have methods like "setMyProperty" and "getMyProperty" to modify and access their fields. In addition to that, collections are an exception to that rule because they don't define a setter method. Instead, they define a method like "addMyItem" to fill the collection called "myItems".

The setter methods don't just set a property. They also contain logic that will mark a property as modified so that queries can be optimized.

The first step in setting up automatic mapping of the client and server objects, is to create Data Transfer Objects (DTO's, also known as Value Objects or VO's - although I prefer DTO after reading Eric Evans' DDD book.) that have the same property names as the protected properties in the PHP classes generated by Propel. To simplify the server objects, we changed the protected scope to public since it then allows us to send these to the client.

So what we have so far is a bunch of classes on the server and a bunch of classes on the client. Sending an object from server to client will allow mapping at this moment since we changed the protected scope of the properties to a public scope. Also note that you need to instruct AMFPHP about the type of the class by defining it in every object you want to map:

Mapping objects from client to server

Mapping objects from client to server is actually not that easy. After all, when we send a property from the client, say "myProperty", the AMFDeserializer inside AMFPHP will try to set a property called "myProperty" on the mapped server object. This would actually work, but the queries would fail to execute correctly since they will not see any properties as being modified. That's why we need to call the setter method "setMyProperty" instead, which will mark the property as modified.

In order to invoke the setters (and "add*" methods of the collections) we changed the AMFDeserializer class so it tries to invoke setters dynamically. Let's jump right into the code.

The above code tries to match the name of the setters by looking at the name of the properties inside the object being send. If it finds a setter method, it will invoke it and pass in the property as a value. The code will also try to detect a collection and invoke the "add*" method instead of a setter. There's also a "isNew" property to instruct the classes whether to do an update or an insert query when the save method is invoked on an object.

This hack brought me to the idea that AMFPHP should maybe provide a pluggable architecture for the serializers and deserializers. Instead of going into the code and modifying it to suit your needs, you could then register a custom (de)serializer in the config which will be used. Upgrading to newer versions of AMFPHP would then be less of a pain.

Anyway, hope you find this useful. Have fun coding!

You can get the files here. The zip file includes the presentation slides, all the examples, the database dumps and the AMFPHP classes.

Many thanks to MMUG Belgium (Serge and Peter) and MultimediaCollege for the venue.

The UserVO class in PHP

This class is in a "vo" subfolder of the "services" folder (in your AMFPHP installation dir).

The UserVO class in AS2

This class is in the namespace "com.domain.vo.UserVO".

Flash to PHP

Sending VO's from Flash to PHP is quite simple. Just add the parameters in the "arguments" key. Use the fully qualified classpath of the class on the server side and make sure you set "required" to true;

PHP to Flash

Watch out here! You can leave out the "returns" key from the method entry in the methodtable. When you do that, AMFPHP will return the name of the class for you. The thing to know here is that in PHP4 the classname will be returned in lowercase, while in PHP5 it will be returned in its original format of lower- and uppercases. Note that this does not return the fully qualified classpath, but just the classname. "uservo" vs. "UserVO".

Here's a quote from the "get_class" function docs.

In PHP 4 get_class() returns a user defined class name in lowercase, but in PHP 5 it will return the class name in it's original notation.
http://be.php.net/manual/en/function.get-class.php

This is not recommended because Object.registerClass() will fail because it is case-sensitive. The best way to get Object.registerClass() to work is to pass in the name of the class in the "returns" key and then use that same name in lowercase to register the class in Flash.

And then in Flash...

That's it, cheers!

[Update] I must have missed something here: the "returns" string is always passed to Flash in lowercase. So remember that when you use Object.registerClass().

 
What about server side generated xml data?

One trick that is often used is to pass in the URL of a server side script in the load() method of the XML object in Flash. That server side script can be a ASP, PHP, JSP or WEP (whatever page - ok, bad joke). What this kind of script actually does is create XML data and write it to the screen. Flash only wants XML data to be passed to an XML object and doesn't care if it's read from a static XML file or from data that is generated dynamically.

 
How do I create XML data on the server?

Probably the most used technique here is to compose a string with XML data and write it to the screen.

This is bad for 2 reasons:

1. You need to make sure that when you open a node, you also close it further in the string. When you're dealing with a lot of XML data things get very messy and you'll most likely forget to close one.

2. As covered in part 1, you need to replace special characters (remember them?) with entity references. What you can do to achieve this, is create a function or a prototype when you are using asp/jscript and call that function or prototype on every text you insert. This may not sound like a disadvantage because you have to replace them anyway, but you'll see that this can done much cleaner and with less work. In addition, you can easily forget to send the text through that function.

 
Using XML DOM

A better way of composing XML data would be to use the XML DOM object. When you're dealing with ASP, you can use Microsoft.XMLDOM. PHP has a DomDocument you can use. Here's an ASP code example.

Note that is it not needed to call the encode function on the data you pass in. This is handled automatically by the XML DOM object. You also can't forget to close nodes, since you're not using strings.

To get the XML data on screen (or load it into Flash), you can call Response.Write() and pass in the xmlDoc.xml property. This will give you a string representation of its data. Also, don't forget to set the codepage of your ASP page to UTF-8. This is the 65001 in the code below.

 
Generating XML files

What if you want to save your XML data in a file on the server? The best way I found is to write a file using ADODB.Stream. That way, you can save your file under UTF-8 encoding which is exactly what we need.

If you're using PHP, you can save UTF-8 files using the pack() function which lets you pack data into binary strings.

When you saved your file on the server, download and open it (notepad) and check its encoding. It should be UTF-8.

 
Wrapping up

That's about it. I hope this article helped you (in whatever way). Feel free to contact me in case you have something to add or came up with other solutions.

Thank you and goodnight!