Project Pages

objSQL Home
Freshmeat
PHP Classes
SourceForge
Downloads
Archived Documentation

DB Connection Methods

objSQL
obj_close

Error Handling Methods

obj_error
obj_error_message

Statement Methods

obj_delete
obj_insert
obj_paging
obj_query
obj_select
obj_update

Resultset Methods

obj_affected_rows
obj_fetch_assoc
obj_fetch_num
obj_fetch_object
obj_field
obj_free_result
obj_num_fields
obj_num_rows

Prepared Statement Methods

obj_bind
obj_close_statement
obj_execute
obj_free_statement
obj_prepare_statement

Transaction Methods

obj_commit
obj_rollback
obj_savepoint
obj_transaction

Utility Methods

obj_escape
obj_info
obj_row_count

obj_transaction

Description:

Initiates a transaction and disables autocommit.

Transactions are a means to ensure a database's integrity when one or more queries fail. Queries are usually grouped together in logical blocks and are committed or rolled back when certain conditions are met. In general, any statement that alters a database record such as insert, delete and update is considered a transactional statement. Statements such as create database, create table, drop database, etc. should be executed outside of a transaction block.

  • It is extremely important to explicitly commit or rollback a transaction block. Failure to do so may have unintended consequences such as a proceeding non-transactional query enabling autocommit and commiting queries in failed transaction blocks.

See also: Nested Transactions

Parameters:

mixed obj_transaction ( void )

Returns:

Transaction instance or false on failure.

Example:

<?php

try
{
    $trans = $dbh->obj_transaction();
    
    $data = array( "color" => "blue",
                   "type"  => "leather",
                   "price" => 36.95 );
                   
    $rs = $dbh->obj_update( "products", $data, "prod_id=21" );
    
    if ( $dbh->obj_error() )
        $trans->obj_rollback();
        
    $trans->obj_commit();    

}
catch ( Exception $e ) 
{
    //log error and/or redirect user to error page
}

?>

See also: obj_commit, obj_rollback, obj_savepoint

Nested Transactions:

Nested transactions are possible with objSQL with the following restrictions:

  • You MUST create a new connection instance for each transaction.
  • PostgreSQL and Oracle require the PDO extension for nested transactions.
  • The current version of SQLite3 compiled with PHP 5, 3.7.7.1, does not support nested transactions.

Example:

<?php

$dbh_1 = new objsql( array("mysql","localhost","root","pass","test_mysql") );
$dbh_2 = new objsql( array("mysql","localhost","root","pass","test_mysql") );

try
{
    $trans_1 = $dbh_1->obj_transaction();
    
    $dbh_1->obj_query( "insert into my_table (f_name,l_name) values('Mother','Load')" );
        
    if ( $dbh_1->obj_error() )
        throw new Exception( $dbh_1->obj_error_message() );
       
    $trans_2 = $dbh_2->obj_transaction();
    
    $dbh_2->obj_query( "insert into my_table (f_name,l_name) values('Land','Mine')" );    
   
    if ( $dbh_2->obj_error() )
        throw new Exception( $dbh_2->obj_error_message() );

    if ( !$trans_2->obj_commit() )
    {
        $trans_2->obj_rollback();
        throw new Exception( $dbh_2->obj_error_message() );
    } 

    if ( !$trans_1->obj_commit() )
    {
        $trans_1->obj_rollback();
        throw new Exception( $dbh_1->obj_error_message() );
    }
    
}
catch ( Exception $e ) 
{
    echo 'Error: ' . $e->getMessage();
} 

?>