Database Modeling and Domain Objects

This page will discuss what you need to do to extend the data model with your own table(s) and create domain objects so they can be used with the Doctrine ORM framework.

To make the examples easier to follow, we will assume that you installed the Ringside source in the directory <trunk> and a new table you want to create in your data model is called "NEW_FOO".

1. When you want to create a new database table, you must first figure out what columns are needed and then figure out what integrity constraints and foreign key relationships belong in that table. Model your new table in your own database schema. That is, create your NEW_FOO directly in your own database using the appropriate SQL DDL commands. Things to consider:
   • All tables should have an integer column named "ID" that is an auto-incremented primary key.
   • Consider having a "CREATED" and/or "MODIFIED" column of type "timestamp". We may have Doctrine automatically manage these columns in the future for you.
2. After you create the table as you like it in your own database, you must run the build-doctrine.xml phing script to generate PHP classes, which essentially imports your schema into Doctrine. Before you run this script, make sure your <trunk>/build/build.local.properties is pointing to the database that has your new table in it.

   cd <trunk>/build
   phing -f build-doctrine.xml import
   

3. After you run the import, verify that you now have new generated files under the directory <trunk>/dist/doctrine. Specifically, you should have these three files created under that directory:
   • ringside/dao/records/RingsideNewFoo.php
   • ringside/dao/records/RingsideNewFooTable.php
   • ringside/dao/records/generated/BaseNewFoo.php
4. Merge the contents found in BaseNewFoo.php into RingsideNewFoo.php. Essentially, RingsideNewFoo.php should now directly extend Doctrine_Record, should not be abstract, and should have the setTableDefinition() and setUp() methods directly defined within it. After you do this, BaseNewFoo.php will no longer be needed or used (you are free to delete it along with its generated directory if you wish).
5. Copy that merged RingsideNewFoo.php file into the Ringside source directory <trunk>/api/includes/ringside/api/dao/records. This is the domain object that your DAO will use when it needs to access your new table's data.
6. Copy the RingsideNewFooTable.php file into the Ringside source directory <trunk>/api/includes/ringside/api/dao/tables.
7. You may have to manually add additional code in the RingsideNewFoo.php if you have additional metadata about your table that is not imported by Doctrine (e.g. double check that all your indexes and unique constraints are properly defined in the code).
8. You should now write your DAO that directly accesses your data. Your DAO is free to invoke any Doctrine API in order to obtain properly populated domain objects. You should name your DAO NewFoo.php and it should be placed in the directory where all the other DAOs live; specifically in the directory <trunk>/api/includes/ringside/api/dao. You must be familiar with Doctrine, its API and Doctrine's DQL query language in order to properly code up a DAO.
9. You can now write one or more business objects (aka "BO") that access your DAO. Your DAOs should only be accessed via business objects. The BOs are the interface used by other parts of the Ringside code base to access your data.

If you wish to re-generate your database schema from the domain objects, you can use that same build-doctrine.xml phing script to do so. First, ensure that all domain objects are valid and then run the "sql" target:

cd <trunk>/build
phing -f build-doctrine.xml sql

You will now find a generated <dbtype>_ringside.sql file under <trunk>/dist.