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.

Since 3.1.2, the connection charset can be set (for MySQL and PostgreSQL databases only) using the Charset property. The value of this property is database dependant. e.g. for mysql, you can use 'latin1' for cp1252 West European, 'utf8' for unicode, ...

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.

  • author: Qiang Xue <qiang.xue@gmail.com>
  • version: $Id: TDbConnection.php 3031 2011-08-28 06:24:03Z GODZilla0480@gmail.com $
  • since: 3.0

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

TComponent
   |
   --TDbConnection
Class Constant Summary
 DEFAULT_TRANSACTION_CLASS = 'System.Data.TDbTransaction'
Method Summary
static array getAvailableDrivers ()
TDbConnection __construct ([string $dsn = ''], [string $username = ''], [string $password = ''], [string $charset = ''])
void close ()
TDbCommand createCommand (string $sql)
boolean getActive ()
mixed getAttribute (int $name)
boolean getAutoCommit ()
string getCharset ()
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 quoteColumnAlias (string $name)
string quoteColumnName (string $name)
string quoteString (string $str)
string quoteTableName (string $name)
void setActive (boolean $value)
void setAttribute (int $name, mixed $value)
void setAutoCommit (boolean $value)
void setCharset (string $value)
void setConnectionString (string $value)
void setPassword (string $value)
void setPersistent (boolean $value)
void setTransactionClass (string $value)
void setUsername (string $value)
void __sleep ()
Methods
static method getAvailableDrivers (line 146)
static array getAvailableDrivers ()
Constructor __construct (line 125)

Constructor.

Note, the DB connection is not established when this connection instance is created. Set Active property to true to establish the connection. Since 3.1.2, you can set the charset for MySql connection

TDbConnection __construct ([string $dsn = ''], [string $username = ''], [string $password = ''], [string $charset = ''])
  • 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.
  • string $charset: Charset used for DB Connection (MySql & pgsql only). If not set, will use the default charset of your database server
beginTransaction (line 342)

Starts a transaction.

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

Closes the currently active DB connection.

It does nothing if the connection is already closed.

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

Creates a command for execution.

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

Obtains a specific DB connection attribute information.

mixed getAttribute (int $name)
  • int $name: the attribute to be queried
getAutoCommit (line 519)
  • 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 ()
getCharset (line 288)
  • return: the charset used for database connection. Defaults to emtpy string.
  • access: public
string getCharset ()
getClientVersion (line 562)
  • return: the version information of the DB driver
  • access: public
string getClientVersion ()
getColumnCase (line 446)
  • return: the case of the column names
  • access: public
TDbColumnCaseMode getColumnCase ()
getConnectionStatus (line 571)
  • return: the status of the connection Some DBMS (such as sqlite) may not support this feature.
  • access: public
string getConnectionStatus ()
getConnectionString (line 239)
  • return: The Data Source Name, or DSN, contains the information required to connect to the database.
  • access: public
string getConnectionString ()
getCurrentTransaction (line 327)
  • return: the currently active transaction. Null if no active transaction.
  • access: public
TDbTransaction getCurrentTransaction ()
getDbMetaData (line 433)
  • access: public
TDbMetaData getDbMetaData ()
getDriverName (line 554)
  • return: name of the DB driver
  • access: public
string getDriverName ()
getLastInsertID (line 378)

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 482)
  • return: how the null and empty strings are converted
  • access: public
TDbNullConversionMode getNullConversion ()
getPassword (line 272)
  • return: the password for establishing DB connection. Defaults to empty string.
  • access: public
string getPassword ()
getPdoInstance (line 305)
  • return: the PDO instance, null if the connection is not established yet
  • access: public
PDO getPdoInstance ()
getPersistent (line 537)
  • return: whether the connection is persistent or not Some DBMS (such as sqlite) may not support this feature.
  • access: public
boolean getPersistent ()
getPrefetch (line 579)
  • return: whether the connection performs data prefetching
  • access: public
boolean getPrefetch ()
getServerInfo (line 587)
  • return: the information of DBMS server
  • access: public
string getServerInfo ()
getServerVersion (line 595)
  • return: the version information of DBMS server
  • access: public
string getServerVersion ()
getTimeout (line 603)
  • return: timeout settings for the connection
  • access: public
int getTimeout ()
getTransactionClass (line 357)
  • return: Transaction class name to be created by calling TDbConnection::beginTransaction. Defaults to 'System.Data.TDbTransaction'.
  • since: 3.1.7
  • access: public
string getTransactionClass ()
getUsername (line 256)
  • return: the username for establishing DB connection. Defaults to empty string.
  • access: public
string getUsername ()
open (line 180)

Opens DB connection if it is currently not

  • throws: TDbException if connection fails
  • access: protected
void open ()
quoteColumnAlias (line 425)

Quotes a column alias for use in a query.

  • return: the properly quoted column alias
  • access: public
string quoteColumnAlias (string $name)
  • string $name: column name
quoteColumnName (line 415)

Quotes a column name for use in a query.

  • return: the properly quoted column name
  • access: public
string quoteColumnName (string $name)
  • string $name: column name
quoteString (line 392)

Quotes a string for use in a query.

string quoteString (string $str)
  • string $str: string to be quoted
quoteTableName (line 405)

Quotes a table name for use in a query.

  • return: the properly quoted table name
  • access: public
string quoteTableName (string $name)
  • string $name: table name
setActive (line 164)

Open or close the DB connection.

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

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 528)
  • 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.
setCharset (line 296)
  • access: public
void setCharset (string $value)
  • string $value: the charset used for database connection
setColumnCase (line 462)
  • access: public
void setColumnCase (TDbColumnCaseMode $value)
setConnectionCharset (line 217)
  • access: protected
void setConnectionCharset ()
setConnectionString (line 248)
void setConnectionString (string $value)
  • string $value: The Data Source Name, or DSN, contains the information required to connect to the database.
setNullConversion (line 498)
  • access: public
void setNullConversion (TDbNullConversionMode $value)
setPassword (line 280)
  • access: public
void setPassword (string $value)
  • string $value: the password for establishing DB connection
setPersistent (line 546)
  • 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.
setTransactionClass (line 367)
  • since: 3.1.7
  • access: public
void setTransactionClass (string $value)
  • string $value: Transaction class name to be created by calling TDbConnection::beginTransaction.
setUsername (line 264)
  • access: public
void setUsername (string $value)
  • string $value: the username for establishing DB connection
__sleep (line 136)

Close the connection when serializing.

  • access: public
void __sleep ()

Redefinition of:
TComponent::__sleep()
Returns an array with the names of all variables of that object that should be serialized.

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::__call()
TComponent::__get()
TComponent::__set()
TComponent::__sleep()
TComponent::__wakeup()
Class Constants
DEFAULT_TRANSACTION_CLASS = 'System.Data.TDbTransaction' (line 90)
  • since: 3.1.7

Documentation generated on Mon, 25 Jun 2012 14:38:00 +0200 by phpDocumentor 1.4.3