Auto Building and Database Schema --
creating the base Classes 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.
/*
* 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 compatibilty
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.
[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 tables() 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.
/*
* 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');
}
}
