Propel API
Class

PropelPDO

class PropelPDO extends PDO

PDO connection subclass that provides the basic fixes to PDO that are required by Propel.

This class was designed to work around the limitation in PDO where attempting to begin
a transaction when one has already been begun will trigger a PDOException. Propel
relies on the ability to create nested transactions, even if the underlying layer
simply ignores these (because it doesn't support nested transactions).

The changes that this class makes to the underlying API include the addition of the
getNestedTransactionDepth() and isInTransaction() and the fact that beginTransaction()
will no longer throw a PDOException (or trigger an error) if a transaction is already
in-progress.

Constants

PROPEL_ATTR_CACHE_PREPARES

Attribute to use to set whether to cache prepared statements.
PROPEL_ATTR_CONNECTION_NAME

Attribute to use to set the connection name usefull for explains
DEFAULT_SLOW_THRESHOLD

DEFAULT_ONLYSLOW_ENABLED

Properties

boolean $useDebug Whether or not the debug is enabled

Methods

__construct(string $dsn, string $username = null, string $password = null, array $driver_options = array())

Creates a PropelPDO instance representing a connection to a database.
setConfiguration(PropelConfiguration $configuration)

Inject the runtime configuration
PropelConfiguration getConfiguration()

Get the runtime configuration
integer getNestedTransactionCount()

Gets the current transaction depth.
boolean isInTransaction()

Is this PDO connection currently in-transaction? This is equivalent to asking whether the current nested transaction count is greater than 0.
boolean isCommitable()

Check whether the connection contains a transaction that can be committed.
boolean beginTransaction()

Overrides PDO::beginTransaction() to prevent errors due to already-in-progress transaction.
boolean commit()

Overrides PDO::commit() to only commit the transaction if we are in the outermost transaction nesting level.
boolean rollBack()

Overrides PDO::rollBack() to only rollback the transaction if we are in the outermost transaction nesting level
boolean forceRollBack()

Rollback the whole transaction, even if this is a nested rollback and reset the nested transaction count to 0.
void setAttribute(integer $attribute, mixed $value)

Sets a connection attribute.
mixed getAttribute(integer $attribute)

Gets a connection attribute.
PDOStatement prepare(string $sql, array $driver_options = array())

Prepares a statement for execution and returns a statement object.
integer exec(string $sql)

Execute an SQL statement and return the number of affected rows.
PDOStatement query()

Executes an SQL statement, returning a result set as a PDOStatement object.
clearStatementCache()

Clears any stored prepared statements for this connection.
integer getQueryCount()

Returns the number of queries this DebugPDO instance has performed on the database connection.
integer incrementQueryCount()

Increments the number of queries performed by this DebugPDO instance.
string getLastExecutedQuery()

Get the SQL code for the latest query executed by Propel
setLastExecutedQuery(string $query)

Set the SQL code for the latest query executed by Propel
useDebug(boolean $value = true)

Enable or disable the query debug features
setLogLevel(integer $level)

Sets the logging level to use for logging method calls and SQL statements.
setLogger(BasicLogger $logger)

Sets a logger to use.
BasicLogger getLogger()

Gets the logger in use.
log(string $msg, integer $level = null, string $methodName = null, array $debugSnapshot = null)

Logs the method call or SQL using the Propel::log() method or a registered logger class.
array getDebugSnapshot()

Returns a snapshot of the current values of some functions useful in debugging.
__destruct()

If so configured, makes an entry to the log of the state of this object just prior to its destruction.

Details

at line 146
public __construct(string $dsn, string $username = null, string $password = null, array $driver_options = array())

Creates a PropelPDO instance representing a connection to a database.

.
If so configured, specifies a custom PDOStatement class and makes an entry
to the log with the state of this object just after its initialization.
Add PropelPDO::__construct to $defaultLogMethods to see this message

Parameters

string $dsn Connection DSN.
string $username The user name for the DSN string.
string $password The password for the DSN string.
array $driver_options A key=>value array of driver-specific connection options.

Exceptions

PDOException if there is an error during connection initialization.

at line 165
public setConfiguration(PropelConfiguration $configuration)

Inject the runtime configuration

Parameters

PropelConfiguration $configuration

at line 175
public PropelConfiguration getConfiguration()

Get the runtime configuration

Return Value

PropelConfiguration

at line 189
public integer getNestedTransactionCount()

Gets the current transaction depth.

Return Value

integer

at line 209
public boolean isInTransaction()

Is this PDO connection currently in-transaction? This is equivalent to asking whether the current nested transaction count is greater than 0.

Return Value

boolean

at line 220
public boolean isCommitable()

Check whether the connection contains a transaction that can be committed.

To be used in an evironment where Propelexceptions are caught.

Return Value

boolean True if the connection is in a committable transaction

at line 230
public boolean beginTransaction()

Overrides PDO::beginTransaction() to prevent errors due to already-in-progress transaction.

Return Value

boolean

at line 253
public boolean commit()

Overrides PDO::commit() to only commit the transaction if we are in the outermost transaction nesting level.

Return Value

boolean

Exceptions

PropelException

at line 282
public boolean rollBack()

Overrides PDO::rollBack() to only rollback the transaction if we are in the outermost transaction nesting level

Return Value

boolean Whether operation was successful.

at line 309
public boolean forceRollBack()

Rollback the whole transaction, even if this is a nested rollback and reset the nested transaction count to 0.

Return Value

boolean Whether operation was successful.

at line 340
public void setAttribute(integer $attribute, mixed $value)

Sets a connection attribute.

This is overridden here to provide support for setting Propel-specific attributes too.

Parameters

integer $attribute The attribute to set (e.g. PropelPDO::PROPEL_ATTR_CACHE_PREPARES).
mixed $value The attribute value.

Return Value

void

at line 362
public mixed getAttribute(integer $attribute)

Gets a connection attribute.

This is overridden here to provide support for setting Propel-specific attributes too.

Parameters

integer $attribute The attribute to get (e.g. PropelPDO::PROPEL_ATTR_CACHE_PREPARES).

Return Value

mixed

at line 389
public PDOStatement prepare(string $sql, array $driver_options = array())

Prepares a statement for execution and returns a statement object.

Overrides PDO::prepare() in order to:
- Add logging and query counting if logging is true.
- Add query caching support if the PropelPDO::PROPEL_ATTR_CACHE_PREPARES was set to true.

Parameters

string $sql This must be a valid SQL statement for the target database server.
array $driver_options One $array or more key => value pairs to set attribute values for the PDOStatement object that this method returns.

Return Value

PDOStatement

at line 420
public integer exec(string $sql)

Execute an SQL statement and return the number of affected rows.

Overrides PDO::exec() to log queries when required

Parameters

string $sql

Return Value

integer

at line 447
public PDOStatement query()

Executes an SQL statement, returning a result set as a PDOStatement object.

Despite its signature here, this method takes a variety of parameters.

Overrides PDO::query() to log queries when required

Return Value

PDOStatement

See also

http://php.net/manual/en/pdo.query.php for a description of the possible parameters.

at line 473
public clearStatementCache()

Clears any stored prepared statements for this connection.

at line 505
public integer getQueryCount()

Returns the number of queries this DebugPDO instance has performed on the database connection.

When using DebugPDOStatement as the statement class, any queries by DebugPDOStatement instances
are counted as well.

Return Value

integer

Exceptions

PropelException if persistent connection is used (since unable to override PDOStatement in that case).

at line 522
public integer incrementQueryCount()

Increments the number of queries performed by this DebugPDO instance.

Returns the original number of queries (ie the value of $this->queryCount before calling this method).

Return Value

integer

at line 532
public string getLastExecutedQuery()

Get the SQL code for the latest query executed by Propel

Return Value

string Executable SQL code

at line 542
public setLastExecutedQuery(string $query)

Set the SQL code for the latest query executed by Propel

Parameters

string $query Executable SQL code

at line 552
public useDebug(boolean $value = true)

Enable or disable the query debug features

Parameters

boolean $value True to enable debug (default), false to disable it

at line 571
public setLogLevel(integer $level)

Sets the logging level to use for logging method calls and SQL statements.

Parameters

integer $level Value of one of the Propel::LOG_* class constants.

at line 583
public setLogger(BasicLogger $logger)

Sets a logger to use.

The logger will be used by this class to log various method calls and their properties.

Parameters

BasicLogger $logger A Logger with an API compatible with BasicLogger (or PEAR Log).

at line 593
public BasicLogger getLogger()

Gets the logger in use.

Return Value

BasicLogger A Logger with an API compatible with BasicLogger (or PEAR Log).

at line 609
public log(string $msg, integer $level = null, string $methodName = null, array $debugSnapshot = null)

Logs the method call or SQL using the Propel::log() method or a registered logger class.

Parameters

string $msg Message to log.
integer $level Log level to use; will use self::setLogLevel() specified level by default.
string $methodName Name of the method whose execution is being logged.
array $debugSnapshot Previous return value from self::getDebugSnapshot().

See also

self::setLogger()

at line 657
public array getDebugSnapshot()

Returns a snapshot of the current values of some functions useful in debugging.

Return Value

array

Exceptions

PropelException

at line 796
public __destruct()

If so configured, makes an entry to the log of the state of this object just prior to its destruction.

Add PropelPDO::__destruct to $defaultLogMethods to see this message

See also

self::log()