Inheritances
Files
Overview
FRAMES
NO FRAMES

Abstract class Doctrine_Connection

Doctrine
|-Doctrine_Connection
|-abstract class Doctrine_Connection extends Doctrine_Configurable implements Countable, IteratorAggregate, Serializable
Doctrine_Connection

A wrapper layer on top of PDO / Doctrine_Adapter

Doctrine_Connection is the heart of any Doctrine based application.

1. Event listeners
An easy to use, pluggable eventlistener architecture. Aspects such as
logging, query profiling and caching can be easily implemented through
the use of these listeners

2. Lazy-connecting
Creating an instance of Doctrine_Connection does not connect
to database. Connecting to database is only invoked when actually needed
(for example when query() is being called)

3. Convenience methods
Doctrine_Connection provides many convenience methods such as fetchAll(), fetchOne() etc.

4. Modular structure
Higher level functionality such as schema importing, exporting, sequence handling etc.
is divided into modules. For a full list of connection modules see
Doctrine_Connection::$_modules
PackageDoctrine
SubpackageConnection
Licensehttp://www.opensource.org/licenses/lgpl-license.php LGPL
Linkwww.phpdoctrine.org
Since1.0
Version$Revision: 5801 $
AuthorKonsta Vesterinen
AuthorLukas Smith (MDB2 library)

Overview

Summary

Static fields
- $supportedDrivers
Instance fields
# $_count
# $_name $_name
# $dbh
# $driverName The name of this connection driver
# $isConnected
- $modules
# $options
# $pendingAttributes
# $properties
# $serverInfo
# $supported
# $tables
Static methods
+ getAvailableDrivers() returns an array of available PDO drivers
+ getSupportedDrivers() Returns an array of supported drivers by Doctrine
Instance methods
+ __construct() the constructor
+ __get() __get
+ __toString() returns a string representation of this object
+ addTable() addTable
+ beginInternalTransaction()
+ beginTransaction() beginTransaction
+ clear() clear
+ close() close
+ commit() commit
+ connect() connect
+ convertBooleans() convertBooleans
+ count() returns the count of initialized table objects
+ create() create
+ createDatabase() createDatabase
+ createQuery() Creates a new Doctrine_Query object that operates on this connection
+ delete() deletes table row(s) matching the specified identifier
+ driverName() converts given driver name
+ dropDatabase() dropDatabase
+ errorCode() errorCode
+ errorInfo() errorInfo
+ evictTables() evictTables
+ exec() exec
+ execute() execute
+ fetchAll() fetchAll
+ fetchArray() fetchArray
+ fetchAssoc() fetchAssoc
+ fetchBoth() fetchBoth
+ fetchColumn() fetchColumn
+ fetchOne() fetchOne
+ fetchRow() fetchRow
+ flush() flush
+ getAttribute() getAttribute
+ getCacheDriver() getCacheDriver
+ getDbh() returns the database handler of which this connection uses
+ getDriverName() getDriverName
+ getIterator() returns an iterator that iterators through all
+ getManager() returns the manager that created this connection
+ getName() getName
+ getOption() getOption
+ getOptions() getOptions
+ getQueryCacheDriver() getQueryCacheDriver
+ getResultCacheDriver() getResultCacheDriver
+ getTable() returns a table object for given component name
+ getTables() returns an array of all initialized tables
+ getTmpConnection() getTmpConnection
+ getTransactionLevel() get the current transaction nesting level
+ hasTable() hasTable
+ incrementQueryCount()
+ insert() Inserts a table row with specified data
+ lastInsertId() lastInsertId
+ modifyLimitQuery() modifyLimitQuery
+ modifyLimitSubquery() Creates dbms specific LIMIT/OFFSET SQL for the subqueries that are used in the
+ prepare() prepare
+ query() query
+ queryOne() query
+ quote() quote
+ quoteIdentifier() Quote a string so it can be safely used as a table or column name
+ quoteMultipleIdentifier() quoteMultipleIdentifier
+ replace() Execute a SQL REPLACE query
+ rethrowException() rethrowException
+ rollback() rollback
+ select() queries the database with limit and offset
+ serialize() Serialize
+ setAttribute() setAttribute
+ setCharset() Set the charset on the current connection
+ setDateFormat() Set the date/time format for the current connection
+ setName() setName
+ setOption() setOption
+ standaloneQuery() standaloneQuery
+ supports() supports
+ unserialize() Unserialize
+ update() Updates table row(s) with specified data

Details

Static fields

$supportedDrivers
private static $supportedDrivers = array( 'Mysql', 'Pgsql', 'Oracle', 'Informix', 'Mssql', 'Sqlite', 'Firebird' )
Var array $supportedDrivers an array containing all supported drivers

Instance fields

$_name
protected $_name
$_name

Name of the connection
Var string $_name
$dbh
protected $dbh
Var $dbh the database handler
$driverName
protected $driverName
The name of this connection driver.
Var string $driverName
$isConnected
protected $isConnected = false
Var boolean $isConnected whether or not a connection has been established
$modules
private $modules = array('transaction' => false, 'expression' => false, 'dataDict' => false, 'export' => false, 'import' => false, 'sequence' => false, 'unitOfWork' => false, 'formatter' => false, 'util' => false, )
See also Doctrine_Connection::__get()
Var array $modules an array containing all modules
transaction Doctrine_Transaction driver, handles savepoint and transaction isolation abstraction

expression Doctrine_Expression driver, handles expression abstraction

dataDict Doctrine_DataDict driver, handles datatype abstraction

export Doctrine_Export driver, handles db structure modification abstraction (contains
methods such as alterTable, createConstraint etc.)
import Doctrine_Import driver, handles db schema reading

sequence Doctrine_Sequence driver, handles sequential id generation and retrieval

unitOfWork Doctrine_Connection_UnitOfWork handles many orm functionalities such as object
deletion and saving

formatter Doctrine_Formatter handles data formatting, quoting and escaping
$pendingAttributes
protected $pendingAttributes = array()
Var array $pendingAttributes An array of pending attributes. When setting attributes
no connection is needed. When connected all the pending
attributes are passed to the underlying adapter (usually PDO) instance.
$properties
protected $properties = array('sql_comments' => array(array('start' => '--', 'end' => "\n", 'escape' => false), array('start' => '/*', 'end' => '*/', 'escape' => false)), 'identifier_quoting' => array('start' => '"', 'end' => '"','escape' => '"'), 'string_quoting' => array('start' => "'", 'end' => "'", 'escape' => false, 'escape_pattern' => false), 'wildcards' => array('%', '_'), 'varchar_max_length' => 255, 'sql_file_delimiter' => ";\n", )
Var array $properties an array of connection properties
$serverInfo
protected $serverInfo = array()
Var array $serverInfo
$supported
protected $supported = array()
Var array $supported an array containing all features this driver supports,
keys representing feature names and values as
one of the following (true, false, 'emulated')
$tables
protected $tables = array()
Var array $tables an array containing all the initialized Doctrine_Table objects
keys representing Doctrine_Table component names and values as Doctrine_Table objects

Static methods

getAvailableDrivers()
public static function getAvailableDrivers( )
returns an array of available PDO drivers
getSupportedDrivers()
public static function getSupportedDrivers( )
Returns an array of supported drivers by Doctrine
Returns array $supportedDrivers

Instance methods

__get()
public function __get( $name)
__get
lazy loads given module and returns it
Parameters
string $name the name of the module to get
Returns Doctrine_Connection_Module connection module
Throws Doctrine_Connection_Exception if trying to get an unknown module
See also Doctrine_Connection::$modules all availible modules
__toString()
public function __toString( )
returns a string representation of this object
Returns string
addTable()
public function addTable( Doctrine_Table $table)
addTable
adds a Doctrine_Table object into connection registry
Parameters
Doctrine_Table $table
Returns boolean
beginInternalTransaction()
public function beginInternalTransaction( $savepoint = null)
Parameters
$savepoint
beginTransaction()
public function beginTransaction( $savepoint = null)
beginTransaction
Start a transaction or set a savepoint.

if trying to set a savepoint and there is no active transaction
a new transaction is being started

Listeners: onPreTransactionBegin, onTransactionBegin
Parameters
string $savepoint name of a savepoint to set
Returns integer current transaction nesting level
Throws Doctrine_Transaction_Exception if the transaction fails at database level
clear()
public function clear( )
clear
clears all repositories
Returns void
close()
public function close( )
close
closes the connection
Returns void
commit()
public function commit( $savepoint = null)
commit
Commit the database changes done during a transaction that is in
progress or release a savepoint. This function may only be called when
auto-committing is disabled, otherwise it will fail.

Listeners: onPreTransactionCommit, onTransactionCommit
Parameters
string $savepoint name of a savepoint to release
Returns boolean false if commit couldn't be performed, true otherwise
Throws Doctrine_Transaction_Exception if the transaction fails at PDO level
Throws Doctrine_Validator_Exception if the transaction fails due to record validations
connect()
public function connect( )
connect
connects into database
Returns boolean
Overriden by connect() in classes : Doctrine_Connection_Mysql, Doctrine_Connection_Sqlite
convertBooleans()
public function convertBooleans( $item)
convertBooleans
some drivers need the boolean values to be converted into integers
when using DQL API

This method takes care of that conversion
Parameters
array $item
Returns void
Overriden by convertBooleans() in class : Doctrine_Connection_Pgsql
count()
public function count( )
returns the count of initialized table objects
Returns integer
create()
public function create( $name)
create
creates a record

create creates a record
Parameters
string $name component name
createDatabase()
public function createDatabase( )
createDatabase

Issue create database command for this instance of Doctrine_Connection
Returns mixed Returns Doctrine_Exception or success string
Overriden by createDatabase() in class : Doctrine_Connection_Sqlite
createQuery()
public function createQuery( )
Creates a new Doctrine_Query object that operates on this connection.
delete()
public function delete( Doctrine_Table $table
array $identifier
)
deletes table row(s) matching the specified identifier
Parameters
Doctrine_Table $table
array $identifier
Returns integer The number of affected rows
Throws Doctrine_Connection_Exception if something went wrong at the database level
driverName()
public function driverName( $name)
converts given driver name
Parameters
$name
dropDatabase()
public function dropDatabase( )
dropDatabase

Issue drop database command for this instance of Doctrine_Connection
Returns mixed Returns Doctrine_Exception or success string
Overriden by dropDatabase() in class : Doctrine_Connection_Sqlite
errorCode()
public function errorCode( )
errorCode
Fetch the SQLSTATE associated with the last operation on the database handle
Returns integer
errorInfo()
public function errorInfo( )
errorInfo
Fetch extended error information associated with the last operation on the database handle
Returns array
evictTables()
public function evictTables( )
evictTables
evicts all tables
Returns void
exec()
public function exec( $query
array $params = array()
)
exec
Parameters
string $query sql query
array $params
Returns PDOStatement|Doctrine_Adapter_Statement
execute()
public function execute( $query
array $params = array()
)
execute
Parameters
string $query sql query
array $params
Returns PDOStatement|Doctrine_Adapter_Statement
fetchAll()
public function fetchAll( $statement
array $params = array()
)
fetchAll
Parameters
string $statement sql query to be executed
array $params
Returns array
fetchArray()
public function fetchArray( $statement
array $params = array()
)
fetchArray
Parameters
string $statement sql query to be executed
array $params
Returns array
fetchAssoc()
public function fetchAssoc( $statement
array $params = array()
)
fetchAssoc
Parameters
string $statement sql query to be executed
array $params
Returns array
fetchBoth()
public function fetchBoth( $statement
array $params = array()
)
fetchBoth
Parameters
string $statement sql query to be executed
array $params
Returns array
fetchColumn()
public function fetchColumn( $statement
array $params = array()
$colnum
)
fetchColumn
Parameters
string $statement sql query to be executed
array $params
int $colnum 0-indexed column number to retrieve
Returns array
fetchOne()
public function fetchOne( $statement
array $params = array()
$colnum
)
fetchOne
Parameters
string $statement sql query to be executed
array $params
int $colnum 0-indexed column number to retrieve
Returns mixed
fetchRow()
public function fetchRow( $statement
array $params = array()
)
fetchRow
Parameters
string $statement sql query to be executed
array $params
Returns array
flush()
public function flush( )
flush
saves all the records from all tables
this operation is isolated using a transaction
Returns void
Throws PDOException if something went wrong at database level
getAttribute()
public function getAttribute( $attribute)
getAttribute
retrieves a database connection attribute
Parameters
integer $attribute
Returns mixed
getCacheDriver() Deprecated
public function getCacheDriver( )
getCacheDriver
getDbh()
public function getDbh( )
returns the database handler of which this connection uses
Returns PDO the database handler
getDriverName()
public function getDriverName( )
getDriverName

Gets the name of the instance driver
Returns void
getIterator()
public function getIterator( )
returns an iterator that iterators through all
initialized table objects


foreach ($conn as $index => $table) {
print $table; // get a string representation of each table object
}
Returns ArrayIterator SPL ArrayIterator object
getManager()
public function getManager( )
returns the manager that created this connection
getName()
public function getName( )
getName
returns the name of this driver
Returns string the name of this driver
getOption()
public function getOption( $option)
getOption

Retrieves option
Parameters
string $option
Returns void
getOptions()
public function getOptions( )
getOptions

Get array of all options
Returns void
getTable()
public function getTable( $name)
returns a table object for given component name
Parameters
string $name component name
Returns object Doctrine_Table
getTables()
public function getTables( )
returns an array of all initialized tables
Returns array
getTmpConnection()
public function getTmpConnection( $info)
getTmpConnection

Create a temporary connection to the database with the user credentials.
This is so the user can make a connection to a db server. Some dbms allow
connections with no database, but some do not. In that case we have a table
which is always guaranteed to exist. Mysql: 'mysql', PostgreSQL: 'postgres', etc.
This value is set in the Doctrine_Export_{DRIVER} classes if required
Parameters
string $info
Returns void
getTransactionLevel()
public function getTransactionLevel( )
get the current transaction nesting level
Returns integer
hasTable()
public function hasTable( $name)
hasTable
whether or not this connection has table $name initialized
Parameters
mixed $name
Returns boolean
insert()
public function insert( Doctrine_Table $table
array $fields
)
Inserts a table row with specified data.
Parameters
Doctrine_Table $table
array $fields
Returns mixed boolean false if empty value array was given,
otherwise returns the number of affected rows
lastInsertId()
public function lastInsertId( $table = null
$field = null
)
lastInsertId

Returns the ID of the last inserted row, or the last value from a sequence object,
depending on the underlying driver.

Note: This method may not return a meaningful or consistent result across different drivers,
because the underlying database may not even support the notion of auto-increment fields or sequences.
Parameters
string $table name of the table into which a new row was inserted
string $field name of the field into which a new row was inserted
modifyLimitQuery()
public function modifyLimitQuery( $query
$limit = false
$offset = false
$isManip = false
)
modifyLimitQuery

Some dbms require specific functionality for this. Check the other connection adapters for examples
Parameters
$query
$limit
$offset
$isManip
Returns string
modifyLimitSubquery()
public function modifyLimitSubquery( Doctrine_Table $rootTable
$query
$limit = false
$offset = false
$isManip = false
)
Creates dbms specific LIMIT/OFFSET SQL for the subqueries that are used in the
context of the limit-subquery algorithm.
Parameters
Doctrine_Table $rootTable
$query
$limit
$offset
$isManip
Returns string
Overriden by modifyLimitSubquery() in class : Doctrine_Connection_Oracle
prepare()
public function prepare( $statement)
prepare
Parameters
string $statement
query()
public function query( $query
array $params = array()
$hydrationMode = null
)
query
queries the database using Doctrine Query Language
returns a collection of Doctrine_Record objects


$users = $conn->query('SELECT u.* FROM User u');

$users = $conn->query('SELECT u.* FROM User u WHERE u.name LIKE ?', array('someone'));
Parameters
string $query DQL query
array $params
int $hydrationMode Doctrine::HYDRATE_ARRAY or Doctrine::HYDRATE_RECORD
Returns Doctrine_Collection Collection of Doctrine_Record objects
queryOne()
public function queryOne( $query
array $params = array()
)
query
queries the database using Doctrine Query Language and returns
the first record found


$user = $conn->queryOne('SELECT u.* FROM User u WHERE u.id = ?', array(1));

$user = $conn->queryOne('SELECT u.* FROM User u WHERE u.name LIKE ? AND u.password = ?',
array('someone', 'password')
);
Parameters
string $query DQL query
array $params
Returns Doctrine_Record|false Doctrine_Record object on success,
boolean false on failure
quote()
public function quote( $input
$type = null
)
quote
quotes given input parameter
Parameters
mixed $input parameter to be quoted
string $type
Returns mixed
quoteIdentifier()
public function quoteIdentifier( $str
$checkOption = true
)
Quote a string so it can be safely used as a table or column name

Delimiting style depends on which database driver is being used.

NOTE: just because you CAN use delimited identifiers doesn't mean
you SHOULD use them. In general, they end up causing way more
problems than they solve.

Portability is broken by using the following characters inside
delimited identifiers:
+ backtick (`) -- due to MySQL
+ double quote (") -- due to Oracle
+ brackets ([ or ]) -- due to Access

Delimited identifiers are known to generally work correctly under
the following drivers:
+ mssql
+ mysql
+ mysqli
+ oci8
+ pgsql
+ sqlite

InterBase doesn't seem to be able to use delimited identifiers
via PHP 4. They work fine under PHP 5.
Parameters
string $str identifier name to be quoted
bool $checkOption check the 'quote_identifier' option
Returns string quoted identifier string
Overriden by quoteIdentifier() in classes : Doctrine_Connection_Informix, Doctrine_Connection_Mssql
quoteMultipleIdentifier()
public function quoteMultipleIdentifier( $arr
$checkOption = true
)
quoteMultipleIdentifier
Quotes multiple identifier strings
Parameters
array $arr identifiers array to be quoted
bool $checkOption check the 'quote_identifier' option
Returns string quoted identifier string
replace()
public function replace( Doctrine_Table $table
array $fields
array $keys
)
Execute a SQL REPLACE query. A REPLACE query is identical to a INSERT
query, except that if there is already a row in the table with the same
key field values, the REPLACE query just updates its values instead of
inserting a new row.

The REPLACE type of query does not make part of the SQL standards. Since
practically only MySQL and SQLIte implement it natively, this type of
query isemulated through this method for other DBMS using standard types
of queries inside a transaction to assure the atomicity of the operation.
Parameters
Doctrine_Table $table
array $fields
array $keys
Returns integer number of rows affected
Throws Doctrine_Connection_Exception if this driver doesn't support replace
Throws Doctrine_Connection_Exception if some of the key values was null
Throws Doctrine_Connection_Exception if there were no key fields
Throws PDOException if something fails at PDO level
Overriden by replace() in class : Doctrine_Connection_Mysql
rethrowException()
public function rethrowException( Exception $e
$invoker
)
rethrowException
Parameters
Exception $e
$invoker
rollback()
public function rollback( $savepoint = null)
rollback
Cancel any database changes done during a transaction or since a specific
savepoint that is in progress. This function may only be called when
auto-committing is disabled, otherwise it will fail. Therefore, a new
transaction is implicitly started after canceling the pending changes.

this method can be listened with onPreTransactionRollback and onTransactionRollback
eventlistener methods
Parameters
string $savepoint name of a savepoint to rollback to
Returns boolean false if rollback couldn't be performed, true otherwise
Throws Doctrine_Transaction_Exception if the rollback operation fails at database level
select()
public function select( $query
$limit
$offset
)
queries the database with limit and offset
added to the query and returns a Doctrine_Connection_Statement object
Parameters
string $query
integer $limit
integer $offset
serialize()
public function serialize( )
Serialize. Remove database connection(pdo) since it cannot be serialized
Returns string $serialized
setAttribute()
public function setAttribute( $attribute
$value
)
setAttribute
sets an attribute
Parameters
integer $attribute
mixed $value
Returns boolean
To do why check for >= 100? has this any special meaning when creating
attributes?
setCharset()
public function setCharset( $charset)
Set the charset on the current connection
Parameters
$charset
setDateFormat()
public function setDateFormat( $format = null)
Set the date/time format for the current connection
Parameters
$format
Returns void
Overriden by setDateFormat() in class : Doctrine_Connection_Oracle
setName()
public function setName( $name)
setName

Sets the name of the connection
Parameters
string $name
Returns void
setOption()
public function setOption( $option
$value
)
setOption

Set option value
Parameters
string $option
$value
Returns void
standaloneQuery()
public function standaloneQuery( $query
$params = array()
)
standaloneQuery
Parameters
string $query sql query
array $params query parameters
Returns PDOStatement|Doctrine_Adapter_Statement
supports()
public function supports( $feature)
supports
Parameters
string $feature the name of the feature
Returns boolean whether or not this drivers supports given feature
unserialize()
public function unserialize( $serialized)
Unserialize. Recreate connection from serialized content
Parameters
string $serialized
Returns void
update()
public function update( Doctrine_Table $table
array $fields
array $identifier
)
Updates table row(s) with specified data
Parameters
Doctrine_Table $table
array $fields
array $identifier
Returns mixed boolean false if empty value array was given,
otherwise returns the number of affected rows
Throws Doctrine_Connection_Exception if something went wrong at the database level