Configuration Options

Configuration Options – Setting the defaults for database access


DB_DataObject needs to be configured before using it and auto generating classes and definitions. The easiest way to configure DB_DataObject is to use ini files (although you may also like to consider the PEAR::Config class, or your own configuration system)

This is a typical configuration file for DB_DataObject


database          = mysql://user:password@localhost/vending
schema_location   = /home/me/Projects/myapplication/DataObjects
class_location    = /home/me/Projects/myapplication/DataObjects
require_prefix    = DataObjects/
class_prefix      = DataObjects_
db_driver         = MDB2 #Use this if you wish to use MDB2 as the driver
quote_identifiers = 1

To use this ini file with DB_DataObject, (and possibly any other classes that use options like this)

Setting the default options

$config as $class=>$values) {
$options = &PEAR::getStaticProperty($class,'options');
$options $values;

// or you can do without an ini file, and configure it in PHP..

$options = &PEAR::getStaticProperty('DB_DataObject','options');
$options = array(
'database'          => 'mysql://user:password@localhost/vending',
'schema_location'   => '/home/me/Projects/myapplication/DataObjects',
'class_location'    => '/home/me/Projects/myapplication/DataObjects',
'require_prefix'    => 'DataObjects/',
'class_prefix'      => 'DataObjects_',
'db_driver'         => 'MDB2'//Use this if you wish to use MDB2 as the driver
'quote_identifiers' => true

Configuration Options - Required

database DSN

This is the default data source name (DSN) to connect to your database. See the DSN configuration page for DB or the DSN configuration page for MDB2 for more details.

schema_location directory

The directory where the DB_DataObject database schema file is store.

DB_DataObject stores the description of the database (Tables and Columns) in an .ini file, in this directory. This information is used to determine if the column is a string and needs quotes, or should be a number (and is checked) at SQL building time. It is quite common to store the schema in the same directory as your DataObject Classes.

require_prefix directory

The Path absolute, or relative to your default include path(s), where your extended classes can be found.

This is used by the staticGet() method and the getLinks() method to auto load classes,

class_prefix string

All the generated Classes are named {class_prefix}ucfirst($table_name) . Use this to alter the prefixed name, this is used by the staticGet() and getLinks() methods

Configuration Options - Optional

db_driver string

default = DB, Use this configuration option to set the database abstraction driver used by DB_DataObject.

using MDB2 as the driver

db_driver = MDB2
sequence_{table} string

To Hard code the key (autoincrement/nextval() for a table to a specific key, overriding anything in the keys definition of the file. Normally used on databases that are not able to be queried correctly for their structure

using login as the key for the person table

sequence_person = login
ignore_sequence_keys string

If you do not want to use pear's nextval(), for automatically filling in sequences, this can disable it for "ALL", or a list of tables "person,cart,group"

debug integer

The default debugging level (default 0=off), 1= basic sql logging,2=result logging, 3=everything

debug_ignore_updates boolean

default FALSE, if set, then updates on the database are disabled.

dont_die boolean

default FALSE, The standard behaviour of dataobjects is to issue a PEAR_ERROR_DIE (eg. exiting PHP), when a fatal error occurs, like database connection failure or sending an invalid object type to a method. However if you need to run it on a live server you will probably want to set this to TRUE and define a PEAR error handler to catch these errors and show a nice friendly 'sorry we are down for maintenence' message page.

quote_identifiers boolean

To force the quotation of identifiers in the SQL statements, set this to 1. This is useful if any table names use hyphens.

Statement Generated with and without quote_identifiers

quote_identifiers = 1;
SELECT 'somecol' FROM 'sometable' WHERE 'somevalue'=1;

quote_identifiers = 0;
SELECT somecol FROM sometable WHERE somevalue=1;

Note: This will not affect data sent to methods such as whereAdd(), orderBy(), and groupBy(), which expect raw data.

proxy string

This enables the building of classes and ini classes on the fly, rather than forcing you to generate the code forhand. (currently the only value supported is "full", which will generate both schema data and default classes when using factory)

Configuration Options - Multiple Databases (optional)

database_* string

When you have multiple databases you can use the database_* to specify the DSN for each database

using multiple databases - database passwords

database_authentication  = mysql://user:password@localhost/authentication
database_sales           = mysql://user:password@localhost/sales
table_* string

When you have multiple databases you can use the table_* configuration variables to map individual tables to different databases, for example

using multiple databases - table settings

table_users     = authentication
table_saleslog  = sales
table_stock     = sales

Configuration Options - Builder

class_location directory

The Directory where your DataObject extended Classes are.

Used by the Class Auto Builder when updating/writing to your class definitions.

extends string

The Name of your Base Class (usually DB_DataObject) is located.

If you wish to add a common layer of useful methods for all classes, you can set the extends_location and extends settings to a different class. the default is 'DB_DataObject'

extends_location directory

The Directory where your Base Class (usually DB_DataObject) is located.

If you wish to add a common layer of useful methods for all classes, you can set the extends_location and extends settings to a different class. the default is 'DB/DataObject.php'

generator_class_rewrite boolean

Normally when you recreate a class from the database, it will only alter the variables, and staticGet, - with this set, it will also update the extends field

build_views boolean

Postgres (and maybe some others), allow you to treat views just like normal tables (eg. insert/update/delete etc. work on them), you can use this option to generate files for all the views in the database.

Note: You will have to specify keys manually in the generated classes (eg. define the methods keys() and sequenceKey(), as the generator can not guess which ones are likely to be the key.

generator_include_regex string

If you only want to generate classes and ini entries for specific tables, you can use this to build a regex, only tables with names matching the regex will be generated, for example /mytables_.*/

generator_exclude_regex string

If you only want to explicitly prevent the generation of classes and ini entries for specific tables, you can use this to build a regex, any tables that match the regex, will not be generated, for example /private_tables_.*/

generator_strip_schema boolean

postgresql has a wierd concept of schemas which end up prefixed to the list of tables. - this makes a mess of class/schema generation setting this to 1, makes the generator strip the schema from the table name

generator_novars boolean

If True, the generator does not write a private or var's definition for the columns so you can overload get/set.

generator_add_validate_stubs boolean

If True, the generator will insert / (or add to existing files) stubs for validate methods.

Introduction (Previous) Auto Building and Database Schema (Next)
Last updated: Tue, 02 Jun 2009 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by:
When using 'generator_include_regex' og 'generator_exclude_regex' with a database that supports schemas (ie. Postgresql), the tablename being matched, will include the schema.

Even if 'strip_schema' is set to true.

And the output from the generator can be a bit confusing, since IF the table is skipped, for not matching the regex, it will write it _with_ the schema name. But whenever the table is generated, it will write out the tablename without the schemaname.
Note by: madsliejensen
In newer versions, somewhere around 1.9.0 i think, generate_links will also work for postgresql!
Note by: madsliejensen
There is an option 'generate_links' which will read foreign keys and add those to the links.ini-file.

However, this currently only works with mysql/mysqli.
Note by: madsliejensen
As of 1.9.0, the factory()-method can check several directories when autoloading dataobjects:

// support for:
// class_location = mydir/ => maps to mydir/Tablename.php
// class_location = mydir/myfile_%s.php => maps to mydir/myfile_Tablename
// with directory sepr
// class_location = mydir/:mydir2/: => tries all of thes locations.
Note by: Mike
If you are having problem making this work and are suspecting that
DataObject is not reading or getting the configuration variables that you are feeding it. try setting them like this

$_DB_DATAOBJECT['CONFIG']['database'] = "mysql://user:password@localhost/db";
$_DB_DATAOBJECT['CONFIG']['schema_location'] = "/var/www/html/mydir";
$_DB_DATAOBJECT['CONFIG']['class_location'] = "/var/www/html/mydir";
$_DB_DATAOBJECT['CONFIG']['db_driver'] = "MDB2";
$_DB_DATAOBJECT['CONFIG']['quote_identifiers'] = true;

This is the only way that I was able to get DataObject to work.
It would not read the variables in an ini file or set them using the
PEAR::setstaticproperty() function.
Note by:
fyi - if you are using the include or exclude regex in an .ini file wrap your regex in double quotes. I found that if I was trying to match table 'users' using '/users/' it choked but "/users/" worked fine.
Note by:
The option db_driver can be used to specify the database driver to use. By default it uses the DB package. You can force DB_DataObject to use MDB2 by adding the following to your configuration: