Class TDbConnection

Description

TDbConnection class

TDbConnection represents a connection to a database.

TDbConnection works together with TDbCommand, TDbDataReader and TDbTransaction to provide data access to various DBMS in a common set of APIs. They are a thin wrapper of the PDO PHP extension.

To establish a connection, set Active to true after specifying ConnectionString, Username and Password.

The following example shows how to create a TDbConnection instance and establish the actual connection:

  1. $connection=new TDbConnection($dsn,$username,$password);
  2. $connection->Active=true;

After the DB connection is established, one can execute an SQL statement like the following:

  1. $command=$connection->createCommand($sqlStatement);
  2. $command->execute(); // a non-query SQL statement execution
  3. // or execute an SQL query and fetch the result set
  4. $reader=$command->query();
  5.  
  6. // each $row is an array representing a row of data
  7. foreach($reader as $row) ...

One can do prepared SQL execution and bind parameters to the prepared SQL:

  1. $command=$connection->createCommand($sqlStatement);
  2. $command->bindParameter($name1,$value1);
  3. $command->bindParameter($name2,$value2);
  4. $command->execute();

To use transaction, do like the following:

  1. $transaction=$connection->beginTransaction();
  2. try
  3. {
  4. $connection->createCommand($sql1)->execute();
  5. $connection->createCommand($sql2)->execute();
  6. //.... other SQL executions
  7. $transaction->commit();
  8. }
  9. catch(Exception $e)
  10. {
  11. $transaction->rollBack();
  12. }

TDbConnection provides a set of methods to support setting and querying of certain DBMS attributes, such as NullConversion.

  • since: 3.0
  • version: $Id: TDbConnection.php 1724 2007-02-23 14:36:02Z xue $
  • author: Qiang Xue <qiang.xue@gmail.com>

Located in /Data/TDbConnection.php (line 80)

TComponent
   |
   --TDbConnection
Method Summary
TDbConnection __construct ([string $dsn = ''], [string $username = ''], [string $password = ''])
void close ()
TDbCommand createCommand (string $sql)
boolean getActive ()
mixed getAttribute (int $name)
boolean getAutoCommit ()
string getClientVersion ()
string getDriverName ()
string getLastInsertID ([string $sequenceName = ''])
string getPassword ()
boolean getPersistent ()
boolean getPrefetch ()
string getServerInfo ()
string getServerVersion ()
int getTimeout ()
string getUsername ()
void open ()
string quoteString (string $str)
void setActive (boolean $value)
void setAttribute (int $name, mixed $value)
void setAutoCommit (boolean $value)
void setConnectionString (string $value)
void setPassword (string $value)
void setPersistent (boolean $value)
void setUsername (string $value)
void __sleep ()
Methods
Constructor __construct (line 99)

Constructor.

Note, the DB connection is not established when this connection instance is created. Set Active property to true to establish the connection.

TDbConnection __construct ([string $dsn = ''], [string $username = ''], [string $password = ''])
  • string $dsn: The Data Source Name, or DSN, contains the information required to connect to the database.
  • string $username: The user name for the DSN string.
  • string $password: The password for the DSN string.
beginTransaction (line 257)

Starts a transaction.

  • return: the transaction initiated
  • access: public
  • throws: TDbException if the connection is not active
TDbTransaction beginTransaction ()
close (line 175)

Closes the currently active DB connection.

It does nothing if the connection is already closed.

  • access: protected
void close ()
createCommand (line 244)

Creates a command for execution.

  • return: the DB command
  • access: public
  • throws: TDbException if the connection is not active
TDbCommand createCommand (string $sql)
  • string $sql: SQL statement associated with the new command.
getActive (line 127)
  • return: whether the DB connection is established
  • access: public
boolean getActive ()
getAttribute (line 467)

Obtains a specific DB connection attribute information.

mixed getAttribute (int $name)
  • int $name: the attribute to be queried
getAutoCommit (line 372)
  • return: whether creating or updating a DB record will be automatically committed. Some DBMS (such as sqlite) may not support this feature.
  • access: public
boolean getAutoCommit ()
getAvailableDrivers (line 119)
array getAvailableDrivers ()
getClientVersion (line 415)
  • return: the version information of the DB driver
  • access: public
string getClientVersion ()
getColumnCase (line 299)
  • return: the case of the column names
  • access: public
TDbColumnCaseMode getColumnCase ()
getConnectionStatus (line 424)
  • return: the status of the connection Some DBMS (such as sqlite) may not support this feature.
  • access: public
string getConnectionStatus ()
getConnectionString (line 184)
  • return: The Data Source Name, or DSN, contains the information required to connect to the database.
  • access: public
string getConnectionString ()
getDriverName (line 407)
  • return: name of the DB driver
  • access: public
string getDriverName ()
getLastInsertID (line 274)

Returns the ID of the last inserted row or sequence value.

string getLastInsertID ([string $sequenceName = ''])
  • string $sequenceName: name of the sequence object (required by some DBMS)
getNullConversion (line 335)
  • return: how the null and empty strings are converted
  • access: public
TDbNullConversionMode getNullConversion ()
getPassword (line 217)
  • return: the password for establishing DB connection. Defaults to empty string.
  • access: public
string getPassword ()
getPdoInstance (line 233)
  • return: the PDO instance, null if the connection is not established yet
  • access: public
PDO getPdoInstance ()
getPersistent (line 390)
  • return: whether the connection is persistent or not Some DBMS (such as sqlite) may not support this feature.
  • access: public
boolean getPersistent ()
getPrefetch (line 432)
  • return: whether the connection performs data prefetching
  • access: public
boolean getPrefetch ()
getServerInfo (line 440)
  • return: the information of DBMS server
  • access: public
string getServerInfo ()
getServerVersion (line 448)
  • return: the version information of DBMS server
  • access: public
string getServerVersion ()
getTimeout (line 456)
  • return: timeout settings for the connection
  • access: public
int getTimeout ()
getUsername (line 201)
  • return: the username for establishing DB connection. Defaults to empty string.
  • access: public
string getUsername ()
open (line 153)

Opens DB connection if it is currently not

  • access: protected
  • throws: TDbException if connection fails
void open ()
quoteString (line 288)

Quotes a string for use in a query.

string quoteString (string $str)
  • string $str: string to be quoted
setActive (line 137)

Open or close the DB connection.

  • access: public
  • throws: TDbException if connection fails
void setActive (boolean $value)
  • boolean $value: whether to open or close DB connection
setAttribute (line 481)

Sets an attribute on the database connection.

void setAttribute (int $name, mixed $value)
  • int $name: the attribute to be set
  • mixed $value: the attribute value
setAutoCommit (line 381)
  • access: public
void setAutoCommit (boolean $value)
  • boolean $value: whether creating or updating a DB record will be automatically committed. Some DBMS (such as sqlite) may not support this feature.
setColumnCase (line 315)
  • access: public
void setColumnCase (TDbColumnCaseMode $value)
setConnectionString (line 193)
void setConnectionString (string $value)
  • string $value: The Data Source Name, or DSN, contains the information required to connect to the database.
setNullConversion (line 351)
  • access: public
void setNullConversion (TDbNullConversionMode $value)
setPassword (line 225)
  • access: public
void setPassword (string $value)
  • string $value: the password for establishing DB connection
setPersistent (line 399)
  • access: public
void setPersistent (boolean $value)
  • boolean $value: whether the connection is persistent or not Some DBMS (such as sqlite) may not support this feature.
setUsername (line 209)
  • access: public
void setUsername (string $value)
  • string $value: the username for establishing DB connection
__sleep (line 109)

Close the connection when serializing.

  • access: public
void __sleep ()

Inherited Methods

Inherited From TComponent

TComponent::addParsedObject()
TComponent::attachEventHandler()
TComponent::canGetProperty()
TComponent::canSetProperty()
TComponent::createdOnTemplate()
TComponent::detachEventHandler()
TComponent::evaluateExpression()
TComponent::evaluateStatements()
TComponent::getEventHandlers()
TComponent::getSubProperty()
TComponent::hasEvent()
TComponent::hasEventHandler()
TComponent::hasProperty()
TComponent::raiseEvent()
TComponent::setSubProperty()
TComponent::__get()
TComponent::__set()

Documentation generated on Sun, 30 Sep 2007 19:15:59 -0400 by phpDocumentor 1.3.0RC4