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

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.

/*
* 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

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');
    }
    
    
    
}