DB_Table_Generator Class Tutorial
Description
The DB_Table_Generator class can generate the PHP code necessary to use the DB_Table package to interact with an existing database. It generates skeleton DB_Table subclass definitions for every table in the database, using table schemas that are obtained by querying the database. It can also generate a file containing the code required to connect to the database, and to create a parent DB_Table_Database object.
Name Conventions and File Structure
All code generated by a DB_Table_Generator object is written to a directory whose path is given by the $class_write_path property of that object. By default, this is the current directory. By default, the name of the class constructed for a table named 'thing' is Thing_Table. That is, the class name is the table name, with the first letter upper case, with an added suffix '_Table'. This suffix can be changed by setting the $class_suffix property. The name of the file containing a subclass definition is the subclass name with a PHP extension, e.g., 'Thing_Table.php'. The name of the object instantiated from that subclass is the same as the table name, with no suffix, e.g., 'thing'.
Code Generation Instructions
To generate the code for all of the tables in a database named $database, instantiate a DB or MDB2 object named $conn that connects to the database of interest, and execute the following code:
Code Generation for an Entire Database
<?php
require_once 'DB/Table/Generator.php';
// [snip] Instantiate DB or MDB2 object $conn
// Instantiate a Generator object
$generator = new DB_Table_Generator($conn, $database);
// Choose a directory for the generated code
$generator->class_write_path = '/var/www/html/app1/db_table' ;
// Generate DB_Table subclass definition files
$generator->generateTableClassFiles();
// Generate the 'Database.php' file
$generator->generateDatabaseFile();
?>
In the above example, '/var/www/html/app1/db_table' is the path (without a trailing directory separator) to a directory in which all of the code should be written. If this directory does not exist, it will be created (if possible). If the directory does already exist, existing files will not be overwritten. If $class_write_path is not set (i.e., if this line from the example is ommitted) all the code will be written to the current directory.
The generateTableClassFiles() method generates skeleton subclass definitions for a set of tables, with different subclass definitions in different files. If it is called with no argument, as above, it generates subclass definitions for all of the tables in the current database.
The generateDatabaseFile() method generates a file, named 'Database.php' by default, that contains all of the additional code necessary to connect to a database and to create a parent DB_Table_Database object. If the generateDatabaseFile() method is called, as in the above example, it must be called after the generateTableClassFiles(). The code in the 'Database.php' file includes (using the "require_once" command) each of the table subclass definition files, instantiates one object of each DB_Table subclass (creating one object per table), instantiates a parent DB_Table_Database object, adds all the tables to that parent, and attempts to guess foreign key relationships between tables based on the column names. This file will generally need to be edited so as to include information about the data source name (DSN), and any foreign key relationships that could not be guessed by the generator.
By default, generateTableClassFiles() and generateDatabaseFiles() generate code for all of the tables in the current database. To generate code for a specified list of tables, set the value of the public $tables property to a sequential list of table names before calling either of these methods. For example, code can be generated for three tables named 'table1', 'table2', and 'table3' as follows:
Code Generation for a Specified Set of Tables
<?php
require_once 'DB/Table/Generator.php'
// [snip] Instantiate DB or MDB2 object $conn
// Instantiate a Generator object
$generator = new DB_Table_Generator($conn, $database);
// Choose a directory for the generated code
$generator->class_write_path = '/var/www/html/app1/db_table' ;
// Define the set of tables
$generator->tables = array('table1', 'table2', 'table3');
// Generate DB_Table subclass definition files
$generator->generateTableClassFiles();
// Generate the 'Database.php' file
$generator->generateDatabaseFile();
?>
If the $tables property of the DB_Table_Generator object is not set to an array value before generateTableClassFiles() is called, then, by default, the generateTableClassFiles() method queries the database for an array of all table names (by calling the getTableNames() method internally), and the $table property is set equal to the resulting array of table names.