Auto Building and Database Schema
What the Auto Builder (createTables.php) does
One of the essential features of an SQL building tool is to to have some understanding of the database structure, So that Integers can be checked, and strings can be escaped. There a few ways that Querying the database for the table structure could be accomplished
- on every SQL query
- At the initialization of every web page.
- Once, while setting up the application, and store it in a file
DB_DataObject uses the last of these normally (see the section below on Alternatives), it utilizes the parse_ini_file function to read the file, so it should be reasonably fast. However this does involve a stage of setting up DB_DataObject prior to use.
The other key concept of DB_DataObject is that you work with extended classes of DB_DataObject, which do all the 'table' related work. Setting up these classes for a large database can be time consuming, so the createTables.php file will automatically build the skeletons for all these class files.
To start the auto builder simply go to the
pear/DB/DataObject/ directory, and type
c:\php4\php.exe createTables.php myconfig.ini this will read your configuration file
and generate all the base classes, along with the data definition file.
As of Version 1.5, you can use the option "proxy = full", which will cause DataObjects to create classes and schema on the fly, rather than using an ini file or prebuilt classes.
Default Class Definition
The default generated class looks like this.
an generated extended class
<?php
/*
* Table Definition for group
*/
class DataObjects_Grp extends DB_DataObject {
###START_AUTOCODE
/* the code below is auto generated do not remove the above tag */
var $__table='group'; // table name
var $id; // int primary_key
var $name; // string
var $grp_owner; // int
var $official; // string
var $street; // string
var $postcode; // string
var $city; // string
var $homepage; // string
var $email; // string
var $extra; // blob
/* Static get */
function staticGet($k,$v=NULL) { return DB_DataObject::staticGet('DataObjects_Grp',$k,$v); }
/* the code above is auto generated do not remove the tag below */
###END_AUTOCODE
}
?>
The class defines the table name, and comments some of table columns for your reference, It also adds the staticGet() method, which can be used to quickly get single rows as Objects. You should add your table related code after the ###END_AUTOCODE.
Prior to version 1.6 a method __clone was created, since PHP5 changed to use $x = clone($y);, this method has been removed. DataObjects now creates a dummy function clone (if necessary), to enable forward compatibility
Database Schema File
The default generated database definition file looks like this, it is located in the directory set by the "schema_location" configuration option, and is named the same as the database.
If you rename the database, you will either have to regenerate the file or copy it to match the same name.
If you change the database schema (eg. add a column or change the type), you will have to regenerate the schema file, using createTables.php, At present, this is not done automatically (although this may be added in the future..)
You should not edit this file by hand (as any changes will be lost when regenerating it). You can override the keys of a table by using a configuration option "sequence_{table} = key", or by defining the sequenceKey() method in your extended class.
Database configuration file
[group] id = 129 name = 130 grp_owner = 129 official = 130 street = 130 postcode = 130 city = 130 homepage = 130 email = 130 extra = 130 [group__keys] id = N
The blocks indicate either tables and the type of field with binary addition (1=integer,2=string,128=not null, so 129=integer and not null), or a list of keys for each table. You should not need to edit file.
Alternatives to using a Schema File
It is possible to use DataObjects without a schema file, this can be achieved in 2 ways
- by defining the table() and keys() methods in an extended class
- by passing an array to table() and keys() when you have an instance of dataobjects
The second of this is demonstrated on the keys() and table() page.
Below is a hand coded class which does not use a schema.ini file.
It was designed to be a return value from a method, rather than an object variable, so that the output of print_r(), would not include extra information (and would be smaller when dumping a large result set.
A Hand Coded extended class
<?php
/*
* Table Definition for group
*/
class DataObjects_Grp extends DB_DataObject {
// you can define these yourself
var $__table='group'; // table name
var $id; // int primary_key
var $name; // string
var $bday; // string
var $last; // datetime
var $active; // tinyint(1)
var $desc; // text
var $photo; // blob
// these are usefull to be consistant with a autogenerated file.
/* Static get */
function staticGet($k,$v=NULL) { return DB_DataObject::staticGet('DataObjects_Grp',$k,$v); }
// now define your table structure.
// key is column name, value is type
function table() {
return array(
'id' => DB_DATAOBJECT_INT,
'name' => DB_DATAOBJECT_STR,
'bday' => DB_DATAOBJECT_STR + DB_DATAOBJECT_DATE,
'last' => DB_DATAOBJECT_STR + DB_DATAOBJECT_DATE + DB_DATAOBJECT_TIME,
'active' => DB_DATAOBJECT_INT + DB_DATAOBJECT_BOOL,
'desc' => DB_DATAOBJECT_STR + DB_DATAOBJECT_TXT,
'photo' => DB_DATAOBJECT_STR + DB_DATAOBJECT_BLOB,
);
}
// now define the keys.
function keys() {
return array('id');
}
}
?>