PEAR Manual
Prev |  | Next

# Auto Building and Database Schema

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.

## Default Class Definition

The default generated class looks like this.

Example 33-1. an generated extended class
    /*
    * 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.

Example 33-2. 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 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.

Example 33-3. A Hand Coded extended class
    /*
    * 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 $grp_owner;                       // int
        var $official;                        // string
        var $street;                          // string
        var $postcode;                        // string
        var $city;                            // string
        var $homepage;                        // string
        var $email;                           // string
        var $extra;                           // 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');
        }

    }

Prev | Home | Next
Configuration Options | Up | DB_DataObject::factory()