<?php
require_once 'DBTableInfo/class.DBTIError.php';

// Modification log
// (date)       (author)    (activity/purpose)
//
// Todo
// (date)       (author)    (activity/purpose)
//


/**
 * This class extracts information about a specified table.
 *
 * This class extracts information from the table specified in the constructor,
 * using the database connected to with the $pearDB parameter.
 * This class relies on the PEAR DB_Common::tableInfo() function, and will only
 * work if this function is properly implemented for your database.
 * This class has only been tested on mySQL and postgreSQL.
 *
 * @author Tommy Gildseth <tommy@akili.no>;
 * @copyright Tommy Gildseth, September 2004
 * @version 0.1
 * @access public
 * @package DB
 */
class DBTableInfo {
    //{{{ Class members
    /**
     * An instance of the PEAR DB class.
     * @access private
     */
    var $_pearDB;

    /**
     * The name of the table information is retrieved from.
     * @access private
     */
    var $_tableName;

    /**
     * The raw info received from a call to DB_common::tableInfo()
     * @access private
     */
    var $_rawInfo;

    /**
     * Array of all the columns in the table
     * @access private
     */
    var $_columns;

    /**
     * Array of all not null columns in the table, not having a default value.
     * @access private
     */
    var $_reqCols = array();

    /**
     * An array containing the names of each of the columns making up the primary key.
     * @access private
     */
    var $_primaryKey;

    /**
     * An array containing information extracted from the flags information returned by
     * the tableInfo() function.
     * @access private
     */
    var $_flags;

    /**
     * An helper class, doing database specific analysis.
     * @access private
     */
    var $_dbHelper;
    // }}}


    //{{{ Constructor(pearDB, table)
    /**
     * Constructor for the DBTableInfo class
     *
     * Based on the table name in $table  and the database connection supplied
     * in $pearDB this method extracts information about the table.
     *
     * @param object    $pearDB An instance of the Pear DB class
     * @param string    $table  The name of the table to find information about.
     * @throws DBTIError
     * @access private
     */
    function DBTableInfo( &$pearDB, $table ) {
        $this->_pearDB = &$pearDB;
        $this->_tableName = $table;

        $load = $this->_loadDBClass();
        if (PEAR::isError($load)) {
            $this = $load;
            return;
        }

        $info = $this->_pearDB->tableInfo($table);

        if (DB::isError($info)) {
            $this = new DBTIError(DBTI_WRONG_TABLE);
            return;
        } else {
            $this->_rawInfo = $info;
            foreach($info as $column) {
                $this->_columns[] = $column['name'];
                $flags = $this->_colInfo($column['flags']);
                if ($flags['primaryKey']) {
                    $this->_primaryKey[] = $column['name'];
                }
                if ($flags['required'] && !$flags['default']) {
                    $this->_reqCols[] = $column['name'];
                }
                $this->_flags[$column['name']] = $flags;
            }
        }
    } // }}} end Constructor


    //{{{ _colInfo(pearDB, table)
    /**
     * Queries the DB specific helper class, to parse the flags for a column
     *
     * @param string    $flags  The string containing a space separated list of column details
     * @access private
     */
    function _colInfo( $flags ) {
        return $this->_dbHelper->parseFlags($flags);
    } // }}} end _colInfo


    //{{{ pkVal(pearDB, table)
    /**
     * Queries the DB specific helper class, to find the column ID value
     *
     * Queries the DB specific helper class, to find the value of the most recently
     * automatically generated value, if available.
     *
     * @throws DBTIError
     * @access public
     */
    function pkVal( ) {
        return $this->_dbHelper->pkValue($this->_pearDB, $this->_flags);
    } // }}} end pkVal


    //{{{ columns( )
    /**
     * Returns an array containing the names of columns from a DB table
     *
     * @return array    An array of column names
     * @access public
     */
    function columns( ) {
        return $this->_columns;
    } // }}} end function columns


    //{{{ reqColumns()
    /**
     * Returns an array containing the names of "not null" columns in a DB table
     *
     * @return array    An array of column names
     * @access public
     */
    function reqColumns( ) {
        return $this->_reqCols;
    } // }}} end function


    //{{{ pKey( )
    /**
     * Returns an array containing the names of the primary key column(s) in a DB table
     *
     * @return array    An array of column names
     * @access public
     */
    function pKey( ) {
        return $this->_primaryKey;
    } // }}} end function pKey


    //{{{ _loadDBClass( )
    /**
     * Loads the helper class for the current database
     *
     * @throws DBTIError
     * @access public
     */
    function _loadDBClass( ) {
        switch($this->_pearDB->dsn['phptype']) {
            case 'mysql':
                include_once 'DBTableInfo/class.DBTIMysql.php';
                $this->_dbHelper = new DBTIMysql();
                break;
            case 'pgsql':
                include_once 'DBTableInfo/class.DBTIPgsql.php';
                $this->_dbHelper = new DBTIPgsql();
                break;
            default:
                return new DBTIError(DBTI_UNSUPORTED_DATABASE);
        }
    } // }}} end function _loadDBClass
}


// testcase
if (false) {
    include '/home/tommy/public_html/isurvey/includes/inc.dbinit.php';
    $foo = new DBTableInfo($pearDB, 'sys_user');
    //print_r($foo->_rawInfo);
} else if (false) {
    include '/home/tommy/public_html/dogsorts/includes/inc.dbinit.php';
    $foo = new DBTableInfo($pearDB, 'breeder');
    print_r($foo);
}

?>