Return to Db.class.php CVS log

Up to [Development] / old-advokit-installer

Initial import of AdvoKit into voter2voter cvs ... I hope you committed your changes. :-) 

<?
#======================================================================
# Database abstraction class.  Loads database-specific
# implementation.
#
# (c) 2003, Dawnstar - http://dawnstar.com - info@dawnstar.com
#======================================================================

#======================================================================
# Metadata object for result sets.
# Extend this for each db you implement (set the values in constructor)
#======================================================================
class MetaData
{
    var $longest;   # longest value of this select
    var $type;      # type of the data
    var $pk;        # true if the column is a primary key, else false
    var $uk;        # true if the column is a unique key, else false
    var $mk;        # true if the column is a non#unique key, else false
}

#======================================================================
# Db class
#======================================================================
class Db
{
    var $logger;
    var $impl;
    var $lastresult;

    #.................................................. Db
    #
    # Create an instance of Db.  If you add a database
    # type, then add a case to the switch statement, and
    # implement all the functions below (the ones that
    # call $this->impl->something).
    #
    function Db( &$config, &$logger )
    {
        define( "W_TBL", $config->get( "db_tblprefix" ) );

        $this->logger =& $logger;

        switch( strtoupper( $config->get( "db_type" ) ) )
        {
            case "MYSQL" :
            {
                require $config->get( "turban_root" )."/Mysql.class.php";
                $this->impl = new Mysql( $config, $logger );
                break;;
            }
            default :
            {
                $logger->error( __FILE__, "Invalid database specified in configuration: '".$config->get( "db_type" )."'" );
            }
        }
    }

    #======================================================================
    # IMPORTANT NOTE:
    # 
    # The following functions are just wrappers around database-specific
    # functions.  Your particular database implementation should
    # do the actual work.
    #======================================================================

    #....................................................... auto_sql_escape
    #
    # Depending on the environment, such as webserver configuration
    # return the escaped version of a given string. For example, 
    # "John's" becomes "John''s".
    #
    # This function exists because some webservers SQL-escape all
    # request parameters, in which case you don't want to do it again.
    #
    # You should use this function for any data received in the
    # request that might need quoting.  For data you generate
    # within the application, use sql_escape().
    #
    function auto_sql_escape( $sql )
    {
        return $this->impl->auto_sql_escape( $sql );
    }
    
    #....................................................... sql_escape
    #
    # Given a string, returns the escaped version of the
    # string.  For example, "John's" becomes "John''s".
    #
    # You should use this function for any data you generate
    # within the application that might need quoting.  For data
    # received in the request, use auto_sql_escape().
    #
    function sql_escape( $sql )
    {
        return $this->impl->sql_escape( $sql );
    }
    
    #....................................................... connect
    #
    # Connect to the database specified by the configuration
    # object passed to the constructor.  The $target argument
    # is for databases (such as oracle) that require extra
    # information in order to establish a connection.
    #
    # The connection handle is kept in an instance variable
    # that is referenced by other functions.  We refer to
    # this as "the current connection".
    #
    # Returns nothing.  
    #
    function connect( $target )
    {
        $this->impl->connect( $target );
    }
    
    #....................................................... disconnect
    #
    # Frees any resources associated with the current
    # connection, including the connection itself.
    #
    # Returns nothing.
    #
    function disconnect()
    {
        $this->impl->disconnect();
    }
    
    #....................................................... begin
    #
    # Begins a transaction.  Theoretically, calls to execute 
    # are not committed until you call commit.
    #
    # Note that some databases may commit your changes for you,
    # depending on what intervening calls to execute() you
    # make.  (e.g. execute( "commit" );
    #
    # Returns nothing.
    #
    function begin()
    {
        $this->impl->begin();
    }
    
    #....................................................... commit
    #
    # Commits a transaction.  After commit(), all changes
    # since the last call to begin() (without an intervening
    # call to rollback() or commit()) are made permanent.
    #
    # Note that some databases may have committed some of
    # your changes already, e.g. if you called something like
    # execute( "commit" ), or if the database doesn't support
    # transactions.
    #
    # Returns nothing.
    #
    function commit()
    {
        $this->impl->commit();
    }
    
    #....................................................... rollback
    #
    # Rolls back a transaction.  After rollback(), all changes
    # since the last call to begin() (without an intervening
    # call to rollback() or commit()) are forgotten.
    #
    # Note that some databases may have committed some of
    # your changes already, e.g. if you called something like
    # execute( "commit" ), or if the database doesn't support
    # transactions.
    #
    # Returns nothing.
    #
    function rollback()
    {
        $this->impl->rollback();
    }
    
    #....................................................... set_til
    #
    # Sets transaction isolation level.  Your choices are:
    #  "READ-UNCOMMITTED"
    #  "READ-COMMITTED"
    #  "REPEATABLE-READ"
    #  "SERIALIZABLE"
    #
    # If you never set this, then the transaction isolation
    # level defaults to whatever was specified in the Configuration
    # object that was passed to the constructor.  If none was
    # specified, then the default is SERIALIZABLE.
    #
    # Returns nothing.
    #
    function set_til( $til )
    {
        $this->impl->set_til( $til );
    }
    
    #....................................................... turn_on_autocommit
    #
    # Turns autocommit on.  After this function returns,
    # subsequent SQL statements will take effect immediately.
    #
    # Returns nothing.
    #
    function turn_on_autocommit()
    {
        $this->impl->turn_on_autocommit();
    }
    
    #....................................................... turn_off_autocommit
    #
    # Turns autocommit off.  If the database supports transactions,
    # then after calling this function, you must call commit()
    # to make any changes take effect.
    #
    # Returns nothing.
    #
    function turn_off_autocommit()
    {
        $this->impl->turn_off_autocommit();
    }
    
    #....................................................... column_names
    #
    # Returns a reference to a numeric array (an array indexed
    # by numerals) of column names for the given table.
    #
    function &column_names( $table )
    {
        return $this->impl->column_names( $table );
    }
    
    #....................................................... column_types
    #
    # Returns a reference to an associative array (an array indexed
    # by column names) of column types for the given table.
    #
    function &column_types( $table )
    {
        return $this->impl->column_types( $table );
    }
    
    #....................................................... column_sizes
    #
    # Returns a reference to an associative array (an array indexed
    # by column names) of column sizes for the given table.
    #
    function &column_sizes( $table )
    {
        return $this->impl->column_sizes( $table );
    }
    
    #....................................................... execute
    #
    # Execute the specified generic sql on the current
    # connection.  
    # 
    # If you use execute() to do a SELECT, only the NUMBER
    # of selected rows will be returned.  Also, a subsequent call
    # to last_select_columns() will NOT get you the column
    # names in the result from such a select.  You probably
    # should use select_all() or select_one() instead.
    #
    # Returns an integer representing how many rows were affected.
    # 
    function execute( $sql )
    {
        return $this->impl->execute( $sql );
    }
    
    #....................................................... last_insert_id
    #
    # Returns the numeric id generated by the previous INSERT
    # of a row containing an AUTO_INCREMENT PRIMARY KEY column.
    #
    # Returns 0 if the previous statement was not an insert,
    # or if the result was indeterminate (e.g. the database
    # can't tell you this information).
    #
    function last_insert_id()
    {
        return $this->impl->last_insert_id();
    }
    
    #....................................................... select
    #
    # Execute $sql in the current connection.  Unlike
    # select_one and select_all, this function returns 
    # a resource id which you can use to fetch result rows
    # and result metadata.
    #
    # If you have aliased a column in a query, then
    # you must use the alias to access that cell in the
    # associative array.
    #
    function select( $sql )
    {
        return $this->impl->select( $sql );
    }
   
    #....................................................... fetch_array
    #
    # Returns an associative array representing the results
    # of the query associated with the specified resource id.
    #
    # If you have aliased a column in a query, then
    # you must use the alias to access that cell in the
    # associative array.
    #
    function fetch_array( $result )
    {
        return $this->impl->fetch_array( $result );
    }

    #....................................................... fetch_row
    #
    # Returns a numeric array representing the results
    # of the query associated with the specified resource id.
    #
    # This is only slightly faster than fetch_array.
    #
    function fetch_row( $result )
    {
        return $this->impl->fetch_row( $result );
    }

    #....................................................... fetch_object
    #
    # Returns an object whose properties match the column
    # names of the next row in the results.
    #
    # This is like fetch_array with some syntactic sugar.
    # Instead of writing:
    #   $row["user_id"]
    # You'd write:
    #   $row->user_id
    #
    function fetch_object( $result )
    {
        return $this->impl->fetch_object( $result );
    }

    #....................................................... select_all
    #
    # Execute $sql in the current connection.  Returns a
    # reference to a numeric array whose cells contain
    # associative arrays indexed by column name.  
    # ALL result rows are included.
    #
    # If you have aliased a column in a query, then
    # you must use the alias to access that cell in the
    # associative array.
    #
    # To get metadata on the select, use last_select_meta().
    #
    function &select_all( $sql, $meta = false )
    {
        $resultset =& $this->impl->select_all( $sql, $meta );
        $count = count($resultset);
        if( 1 == $count )
        {  
            $this->lastresult = "1 record ";
        }        
        else
        {  
            $this->lastresult = "$count records ";
        }        
        return $resultset;
    }
    
    #....................................................... select_range
    #
    # Execute $sql in the current connection.  Returns a
    # reference to a numeric array whose cells contain
    # associative arrays indexed by column name.  
    # The $index parameter specifies the 0-based index
    # representing the first record to be included.
    # The $count parameter specifies the maximum number
    # of rows to return, starting at $index.
    #
    # If you have aliased a column in a query, then
    # you must use the alias to access that cell in the
    # associative array.
    #
    # To get metadata on the select, use last_select_meta().
    #
    function &select_range( $sql, $index = 0, $count=1, $meta = false )
    {
        $resultset =& $this->impl->select_range( $sql, $index, $count, $meta );
        $count = count($resultset);
        if( 1 == $count )
        {  
            $this->lastresult = "1 record ";
        }        
        else
        {  
            $this->lastresult = "$count records ";
        }        
        return $resultset;
    }

    #....................................................... select_one
    #
    # Execute $sql in the current connection.  Returns a
    # reference to associative array indexed by column name, or
    # false if there were no results.
    #
    # If you have aliased a column in a query, then
    # you must use the alias to access that cell in the
    # associative array.
    #
    # To get metadata on the select, use last_select_meta().
    #
    function &select_one( $sql, $meta = false )
    {
        $this->lastresult = "1 record ";
        return $this->impl->select_one( $sql, $meta );
    }
    
    #....................................................... last_select_meta
    #
    # If the last select was a select_one, then return a reference
    # to an associative array containing a metadata object for each
    # selected column.  The object has the following properties:
    # 
    # size   - size of the data
    # type   - type of the data
    # pk     - true if the column is a primary key, else false
    # uk     - true if the column is a unique key, else false
    # mk     - true if the column is a non-unique key, else false
    #
    # If a select_all() was last performed, then a reference to
    # a numeric array is returned.  In this case, each cell contains
    # an array as described above.
    #
    # Results are undefined if the last select was not select_one
    # or select_all.
    #
    function &last_select_meta()
    {
        return $this->impl->meta;
    }

    #....................................................... last_error
    #
    # Returns a two-element numeric array containing
    #   'code'    - the last error number or code
    #   'message' - text associated with 'code'
    #
    # If no error occurred, returns NULL;
    #
    function last_error()
    {
        return $this->impl->last_error();
    }

    #....................................................... affected_rows
    #
    # Returns a the number of rows affected by the last
    # insert, delete, or update.
    #
    function affected_rows()
    {
        return $this->impl->affected_rows();
    }
}


?>