lawngnome
Project home

Summary	PHP OO DB Model inspired by Django
Categories	libraries, construction
Owner(s)	begby

Mission

Lawngnome is a php 5 database model loosely based on the Django model. The goal is to have a very flexible model library that can be used in any framework. The model will handle joins and also multi-table heirarchies created by extending models. The proposed features are as follows:

• Class structure extensible at the model, table, or field level
• Ability to predefine relationships and joins, or create relationships at runtime
• Ability to predefine a model, or create/modify it at runtime
• Models have the optional ability to render html form fields using a set of extensible HTML widget objects.
• Easy to use syntax with heavy use of overloading and SPL allowing you to access model properties and subobjects through an array-like interface.
• Auto-admin interface for objects that implement a model and queryset interface
• Predefined extensible objects that implement the model interface for complex structures such as a pre-order nested set tree
• As a later milestone implement autogenerating models from existing databases, create tables from a model, or create models from an XML defenition

Why one more DB abstraction class?

Lawngnome is meant to be quick to deploy, easy to setup and use, and not require special configuration scripts, compiling, or xml definitions. Additionally it uses a verbose syntax for accessing and defining object properties and for declaring models. Taking advantage of the input widgets can also provide reusable and easy to deploy forms with built in data validation.

Lawngnome is completely independent of any framework and will stay that way

Project Status

The source is posted and is documented with docblocks. It includes a packager that uses autoload, browsing the packager source should show you how to integrate it with your current autload function if you have one setup. My current tasks are to create basic documentation for setup and usage, then to streamline the files so they are easy to setup and test along with some example files.

Class Overview

HTMLWidgets

The widgets are optional helpers used to render form fields. The class is easy to extend and modify to allow custom fields to be created and reused

DataField

The datafield is a representation of an individual field. This object has a validator and sometimes a widget as a member. This field is also relatively simple to extend and has many methods which can be overridden.

Joins are created using a datafield that acts as an adapter to other models demonstrating the flexibility of extending the abstract datafield class.

Model

The model is a collection of fields and/or models and is reponsible for updates, inserts, and deletes on a single model instance. The model also returns information about the modeled database structure such as field names, table names, and join clauses.

The model class the heart of lawngnome. Extend it and implement the abstract methods to be on your way.

QuerySet

The queryset object is used to query the database and create model collections from query results

Quick and Dirty Usage Example

At first glance this does everything that every other db class out there does

$model = new MyModel() ;
$model->find(3) ; <-- Fetch by primary key
$model->myfield = 'somevalue' ; <-- Change the value
$model->save() ; <-- Update it

Field access
However, lawngnome is able to access individual fields as objects or values

$model->myfield ; // Gets the field value
$model['myfield'] ; // Access the field as an object
echo $model->myfield ; // echo the raw value
echo $model['myfield'] ; // Call __toString() on the datafield
 
echo $model['foreignkey']->foreignfield ; // Access a foreign field value from a related model


Field Rendering
Lawngnome can also render form fields and change validation on the fly

// Given a field that uses a text widget input
$model->['field']->input()->size(10)->maxlength(20) ;
echo $model->input(); // Draw the form field
 
// Setup the password field so that it is required with a min length of 8
// then pass the value to php's md5() before inserts or updates
$model->['password']->validator()->required->min_length(8)->md5 ;

SPL implementation

// Loop through all the datafields in the root model and draw input
foreach( $model as $datafield )
{
echo $datafield->input() ;
}
 
// Recursively loop through all joined fields, validate and then draw form input
foreach( $model->GetRecursiveIterator() as $datafield )
{
if( !$datafield->validate() ) echo $datafield->validator()->error() ;
echo $datafield->input() ;
}
 
// Loop through all the html parameters of an html widget
foreach( $model['myfield']->input() as $param => $value )
{
echo $param.':'.$value ;
}


QuerySet Usage

$query = new QuerySet( 'modelname' ) ;
$modelobjects = $query->fieldname->EQ('10')->otherfield->LIKE('%val')->mydate->GTE(time())->RunQuery() ;


The above is only a portion of the features, full documentation coming soon.