## 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:

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

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

     $command=$connection->createCommand($sqlStatement);
     $command->execute();   // a non-query SQL statement execution
     // or execute an SQL query and fetch the result set
      $reader=$command->query();

     // each $row is an array representing a row of data
      foreach($reader as $row) ...

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

     $command=$connection->createCommand($sqlStatement);
     $command->bindParameter($name1,$value1);
     $command->bindParameter($name2,$value2);
     $command->execute();

To use transaction, do like the following:

     $transaction=$connection->beginTransaction();
     try
     {
        $connection->createCommand($sql1)->execute();
        $connection->createCommand($sql2)->execute();
        //.... other SQL executions
            $transaction->commit();
     }
     catch(Exception $e)
     {
        $transaction->rollBack();
     }

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 2760 2010-02-08 07:19:50Z godzilla80@gmx.net $
- author: Qiang Xue <qiang.xue@gmail.com>

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

    TComponent
       |
       --TDbConnection

Class Constant Summary
DEFAULT_TRANSACTION_CLASS = 'System.Data.TDbTransaction'
Method Summary
TDbConnection __construct ([string $dsn = ''], [string $username = ''], [string $password = ''], [string $charset = ''])
TDbTransaction beginTransaction ()
void close ()
TDbCommand createCommand (string $sql)
boolean getActive ()
mixed getAttribute (int $name)
boolean getAutoCommit ()
array getAvailableDrivers ()
string getCharset ()
string getClientVersion ()
TDbColumnCaseMode getColumnCase ()
string getConnectionStatus ()
string getConnectionString ()
TDbTransaction getCurrentTransaction ()
string getDriverName ()
string getLastInsertID ([string $sequenceName = ''])
TDbNullConversionMode getNullConversion ()
string getPassword ()
PDO getPdoInstance ()
boolean getPersistent ()
boolean getPrefetch ()
string getServerInfo ()
string getServerVersion ()
int getTimeout ()
string getTransactionClass ()
string getUsername ()
void open ()
string quoteString (string $str)
void setActive (boolean $value)
void setAttribute (int $name, mixed $value)
void setAutoCommit (boolean $value)
void setCharset (string $value)
void setColumnCase (TDbColumnCaseMode $value)
void setConnectionCharset ()
void setConnectionString (string $value)
void setNullConversion (TDbNullConversionMode $value)
void setPassword (string $value)
void setPersistent (boolean $value)
void setTransactionClass (string $value)
void setUsername (string $value)
void __sleep ()
Methods
Constructor __construct (line 120)

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

- access: public
- see: http://www.php.net/manual/en/function.PDO-construct.php

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 334)

Starts a transaction.

- return: the transaction initiated
- access: public
- throws: TDbException if the connection is not active

TDbTransaction beginTransaction ()
close (line 201)

Closes the currently active DB connection.

It does nothing if the connection is already closed.

- access: protected

void close ()
createCommand (line 308)

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 149)

- return: whether the DB connection is established
- access: public

boolean getActive ()
getAttribute (line 563)

Obtains a specific DB connection attribute information.

- return: the corresponding attribute information
- access: public
- see: http://www.php.net/manual/en/function.PDO-getAttribute.php

mixed getAttribute (int $name)

- int $name: the attribute to be queried

getAutoCommit (line 468)

- 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 141)

- return: list of available PDO drivers
- static:
- access: public
- see: http://www.php.net/manual/en/function.PDO-getAvailableDrivers.php

array getAvailableDrivers ()
getCharset (line 280)

- return: the charset used for database connection. Defaults to emtpy string.
- access: public

string getCharset ()
getClientVersion (line 511)

- return: the version information of the DB driver
- access: public

string getClientVersion ()
getColumnCase (line 395)

- return: the case of the column names
- access: public

TDbColumnCaseMode getColumnCase ()
getConnectionStatus (line 520)

- return: the status of the connection Some DBMS (such as sqlite) may not support this feature.
- access: public

string getConnectionStatus ()
getConnectionString (line 231)

- return: The Data Source Name, or DSN, contains the information required to connect to the database.
- access: public

string getConnectionString ()
getCurrentTransaction (line 319)

- return: the currently active transaction. Null if no active transaction.
- access: public

TDbTransaction getCurrentTransaction ()
getDriverName (line 503)

- return: name of the DB driver
- access: public

string getDriverName ()
getLastInsertID (line 370)

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

- return: the row ID of the last row inserted, or the last value retrieved from the sequence object
- access: public
- see: http://www.php.net/manual/en/function.PDO-lastInsertId.php

string getLastInsertID ([string $sequenceName = ''])

- string $sequenceName: name of the sequence object (required by some DBMS)

getNullConversion (line 431)

- return: how the null and empty strings are converted
- access: public

TDbNullConversionMode getNullConversion ()
getPassword (line 264)

- return: the password for establishing DB connection. Defaults to empty string.
- access: public

string getPassword ()
getPdoInstance (line 297)

- return: the PDO instance, null if the connection is not established yet
- access: public

PDO getPdoInstance ()
getPersistent (line 486)

- return: whether the connection is persistent or not Some DBMS (such as sqlite) may not support this feature.
- access: public

boolean getPersistent ()
getPrefetch (line 528)

- return: whether the connection performs data prefetching
- access: public

boolean getPrefetch ()
getServerInfo (line 536)

- return: the information of DBMS server
- access: public

string getServerInfo ()
getServerVersion (line 544)

- return: the version information of DBMS server
- access: public

string getServerVersion ()
getTimeout (line 552)

- return: timeout settings for the connection
- access: public

int getTimeout ()
getTransactionClass (line 349)

- return: Transaction class name to be created by calling TDbConnection::beginTransaction. Defaults to 'System.Data.TDbTransaction'.
- access: public
- since: 3.1.7

string getTransactionClass ()
getUsername (line 248)

- return: the username for establishing DB connection. Defaults to empty string.
- access: public

string getUsername ()
open (line 175)

Opens DB connection if it is currently not

- access: protected
- throws: TDbException if connection fails

void open ()
quoteString (line 384)

Quotes a string for use in a query.

- return: the properly quoted string
- access: public
- see: http://www.php.net/manual/en/function.PDO-quote.php

string quoteString (string $str)

- string $str: string to be quoted

setActive (line 159)

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 577)

Sets an attribute on the database connection.

- access: public
- see: http://www.php.net/manual/en/function.PDO-setAttribute.php

void setAttribute (int $name, mixed $value)

- int $name: the attribute to be set
- mixed $value: the attribute value

setAutoCommit (line 477)

- 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 288)

- access: public

void setCharset (string $value)

- string $value: the charset used for database connection

setColumnCase (line 411)

- access: public

void setColumnCase (TDbColumnCaseMode $value)

- TDbColumnCaseMode $value: the case of the column names

setConnectionCharset (line 212)

- access: protected

void setConnectionCharset ()
setConnectionString (line 240)

- access: public
- see: http://www.php.net/manual/en/function.PDO-construct.php

void setConnectionString (string $value)

- string $value: The Data Source Name, or DSN, contains the information required to connect to the database.

setNullConversion (line 447)

- access: public

void setNullConversion (TDbNullConversionMode $value)

- TDbNullConversionMode $value: how the null and empty strings are converted

setPassword (line 272)

- access: public

void setPassword (string $value)

- string $value: the password for establishing DB connection

setPersistent (line 495)

- 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 359)

- access: public
- since: 3.1.7

void setTransactionClass (string $value)

- string $value: Transaction class name to be created by calling TDbConnection::beginTransaction.

setUsername (line 256)

- access: public

void setUsername (string $value)

- string $value: the username for establishing DB connection

__sleep (line 131)

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()

Class Constants
DEFAULT_TRANSACTION_CLASS = 'System.Data.TDbTransaction' (line 90)

- since: 3.1.7

Documentation generated on Mon, 22 Feb 2010 12:17:34 +0000 by phpDocumentor 1.3.0RC4