Dynamically Manage Models with Zend_CodeGenerator

The holidays have passed and at last I’ve gotten enough of my obligations out of the way to begin to innovate on some new code as well as play with some of the new offerings in the latest versions of the Zend Framework. I’ve been most interested in particular with Zend_CodeGenerator since I have spent a lot of time in the last year writing boilerplate code for various projects. I find that the bulk of my time is spent prototyping models so I figured it would not be hard to build a model scaffolding script not unlike the ‘rake’ command in ruby on rails and similar commandline tools offered by the many application platforms out there. Rather than killing my wrists pounding out models, their various attributes and associated mutators/accessors, I decided that my time would be more efficiently spent describing my models using a short hand format (preferably xml) and then having a script translate that into actual classes and files. The Doctrine ORM allows you do this very thing translating YAML into Doctrine Models. This was very interesting to me but I chose to take it a step further and have it build all of my Domain Model infrastructure while it was at it (This includes the models, the gateway classes, and the DAO classes).

Zend_CodeGenerator is a very handy module in that it uses reflection to to modify existing classes. This opens a world of possibilities for us since we can generate our models and then carry on customizing them with hand written code, and then come back at a later date and modify the model from our xml. Our models can have their data structures managed by our nifty scaffolding script while leaving all of our after-market customizations untouched when we update our classes. It’s like having your cake and eating it too (YUM!).

So here is an example of how I extended Zend_CodeGenerator classes to build classes specifically for my application platform. This particular example builds gateway classes that extend my Doctrine ORM Adapter (Read about that here) so this is unlikely to be a turnkey drop in solution but it’s really easy to write your own scaffolding classes to suit your needs.

Let’s start with the model schema. Here is an example schema i’ve created that describes my models:

/config/schema.xml:

This xml file describes 4 models (Blog, Post, Comment, and User). It should be clear that we are creating models for a very simple Blogging application. In each model we describe the fields we want and their data types as well as any additional field attributes. We also describe the relationships between the models that map to table relationships. With this schema, I intend to dynamically generate all the files relating to the models.

You can reference the Zend_CodeGenerator section of the reference manual here, so I won’t bore you with the details of the base classes. The examples provided show how the classes can be used directly to provide reflection as well as construct new classes and save them into files. I use it as more of a framework as it suggests you can do, and I chose to extend the classes provided by the module with custom builder classes, each responsible for generating it’s own aspect of the domain. There is a builder class for the stubbed models, one for the gateway class, one for the DAO class as well as builders for application specific abstraction classes. Let’s start with the scaffolding script that utilizes these classes.

/scripts/mm.php:

This script lives in /scripts alongside the rest of my application platform (You can read about the folder hierarchies in some of my earlier posts) and is designed to be run from the command line. I include my bootstrapping file in order to harness that setting of my inclue paths but you can just as easily configure your include path directly in this script as long as you remember to include your Zend folder and configure your autoloader. The script requires you to pass in the -s option and the path to your xml schema file. The script will parse your schema file and use our builder classes to create php files and place them in the correct folders.

It’s worth noting that the scaffolding script is not aware of how the classes are actually built, it only knows how to parse the schema file and convert it into data that the builder class constructors can consume. For the most part, all this script is doing is extracting the application namespace, the models, their attributes, and their relationships and letting the builder classes do all the work. This script can easily be extended to generate different types of classes with the data it extracts.

Before processing the models, we first create an abstract Gateway, Model, and Collection class that will be extended by all of our other classes. We do this in order to facilitate easy customization of all subclasses by providing an empty parent class that in turn extends the platform’s base model classes.

/lib/FP/Model/Gateway/Abstract/Builder.php:

You’ll probably notice this class extends another custom class called FP_Class_Builder. This is nothing more than another abstraction class which provides some base reusable functionality that we need in our builders, such as the ability to convert class names from camel case and back and some other misc methods which I won’t bore you with. The FP_Class_Builder extends Zend_CodeGenerator_PHP_Class giving all of the functionality provided from that class including the ability to reflect, get/set properties and methods, etc. What I have done in each class is extend the constructor to build the class names using the conventions my application platform uses. For the abstract gateway, since it is not model specific, we simply build the class name with the name of the application. With an app name of ‘Blog’ as specified in the schema, the name of this class will be ‘Blog_Gateway’. All model gateways will extend this class. The two other classes the scaffolder initially builds are similar except that they build abstraction classes for the models themselves, and the model collection.

Next we loop through each model node in the schema and pass it into our method for parsing the model information.

First the attributes are parse for each model. They are stored in an associative array along with any recognizable attributes it can get from each node. The attributes tags themselves are the datatype to be used and the text inside is the name. As you can see in the example, each attribute can have the typical configuration associated with database columns such as the ability to force the field to be required. This can be extended to include validation configuration as well pretty easily.

Most of the complexity in these class builders involve defining relationships between models. From the schema you can see there are three relationship types defined: hasone, hasmany, and lookup (many to many). These map perfectly to relational SQL relationships. The tag itself is clearly the type of relationship, and the value inside of the tag is the model it has the relationship with. The model name is used, since the rest can be inferred by convention. The alias attribute is the name by which the related model is reference. In the example above, the relationship to the User model would use the alias ‘Administrators’ and the resulting getter would be called ‘getAdministrators’.

Any time a many-to-many (ie lookup) relationship is defined, a lookup table must be built, and as a result, a DAO class must be built for that lookup table. That is why there is a one-off class built using the FP_Model_Gateway_Doctrine_Builder.

For each model defined, we create 3 classes: The model class, the DAO class, and the gateway class. It should be noted that if you are not using a domain model programming approach, you can probably simplify this to just one class (ie the model). Each class is constructed with a distinct builder class. To each we pass our attributes and relationships and in return we get a class which we can save to a file. If no file path is passed to the call to ‘generateFile’, it will save the class to a location that follows the convention of my own application platform.

/lib/FP/Model/Builder.php:

This is the model builder. It takes the application name, the model name, an array of attributes, and an array of relationships and from there it can construct our stubbed model. Attributes are stored in an associative assigned to a class property called ‘_data’ as per my convention. Relationships are translated into lazy loaded properties and the methods needed to populate those properties from the gateway.

If the scaffolding script is ran more than once and the generated model already exists, the existing class will first be reflected and remembered. While the new class is being generated, any custom methods and/or properties that are defined in the old code but not in the schema, are merged into the new class and the old class is replaced.

From our schema, it should generate a Post class that looks as follows:

/app/default/models/BlogPost.php:

The gateway builder is similar in function:

/lib/FP/Model/Gateway/Builder.php:

The generated gateway class will extend the abstract Blog_Gateway class and as a result will use whatever ORM adapter the parent class is configured to use. From the defined relationships, this class will build out the implementations for fetching related records from foreign gateway classes. The resulting Post gateway class should look like the following:

/app/default/lib/Blog/Posts.php:

Finally here is the builder class for the DAO model:

/lib/FP/Model/Gateway/Doctrine/Builder.php:

This class builds our ORM model. Our ORM is Doctrine in this case, but this class can be replaced by another version supporting the ORM of your choice. This class will build our DAO class which extends Doctrine_Record and defines the columns on the table that this class abstracts as well as the relationships between this table and other tables.

The resulting class for our Post DAO class should look as follows:

/app/default/lib/Blog/Dao/Post.php:

Now that we have all of our pieces in place we can leverage Doctrines migration tools to generate some migrations for us. My migration generating script looks like this:

/public/util/generate_migrations.php:

This script will scan all of my models and generate migrations for them and place them in /db/migrations.

For reference, here is the FP_Class_Builder base class:

/lib/FP/Class/Builder.php:

Here is the base functionality for storing the class in a physical file as well as methods to convert to and from camel case.

So with a simple command from the command line (./mm.php -s ../config/schema.xml), all of my model infrastructure is instantly generated so I am now free to begin by writing my controllers and views. One idea to extend this further is to write a builder script for the model-specific controllers which could house all of the CRUD actions. I see this methodology evolving as an integral part of my own platform, hopefully you can derive some uses for it in your own.