Propel API
Class

DebugPDO

class DebugPDO extends PropelPDO

PDO connection subclass that provides some basic support for query counting and logging.

This class is ONLY intended for development use. This class is also a work in-progress
and, as such, it should be expected that this class' API may change.

The following runtime configuration items affect the behaviour of this class:

- debugpdo.logging.innerglue (default: ": ")
String to use for combining the title of a detail and its value

- debugpdo.logging.outerglue (default: " | ")
String to use for combining details together on a log line

- debugpdo.logging.realmemoryusage (default: false)
Parameter to memory_get_usage() and memory_get_peak_usage() calls

- debugpdo.logging.methods (default: DebugPDO::$defaultLogMethods)
An array of method names ("Class::method") to be included in method call logging

- debugpdo.logging.onlyslow (default: false)
Suppress logging of non-slow queries.

- debugpdo.logging.details.slow.enabled (default: false)
Enables flagging of slow method calls

- debugpdo.logging.details.slow.threshold (default: 0.1)
Method calls taking more seconds than this threshold are considered slow

- debugpdo.logging.details.time.enabled (default: false)
Enables logging of method execution times

- debugpdo.logging.details.time.precision (default: 3)
Determines the precision of the execution time logging

- debugpdo.logging.details.time.pad (default: 10)
How much horizontal space to reserve for the execution time on a log line

- debugpdo.logging.details.mem.enabled (default: false)
Enables logging of the instantaneous PHP memory consumption

- debugpdo.logging.details.mem.precision (default: 1)
Determines the precision of the memory consumption logging

- debugpdo.logging.details.mem.pad (default: 9)
How much horizontal space to reserve for the memory consumption on a log line

- debugpdo.logging.details.memdelta.enabled (default: false)
Enables logging differences in memory consumption before and after the method call

- debugpdo.logging.details.memdelta.precision (default: 1)
Determines the precision of the memory difference logging

- debugpdo.logging.details.memdelta.pad (default: 10)
How much horizontal space to reserve for the memory difference on a log line

- debugpdo.logging.details.mempeak.enabled (default: false)
Enables logging the peak memory consumption thus far by the currently executing PHP script

- debugpdo.logging.details.mempeak.precision (default: 1)
Determines the precision of the memory peak logging

- debugpdo.logging.details.mempeak.pad (default: 9)
How much horizontal space to reserve for the memory peak on a log line

- debugpdo.logging.details.querycount.enabled (default: false)
Enables logging of the number of queries performed by the DebugPDO instance thus far

- debugpdo.logging.details.querycount.pad (default: 2)
How much horizontal space to reserve for the query count on a log line

- debugpdo.logging.details.method.enabled (default: false)
Enables logging of the name of the method call

- debugpdo.logging.details.method.pad (default: 28)
How much horizontal space to reserve for the method name on a log line

The order in which the logging details are enabled is significant, since it determines the order in
which they will appear in the log file.

Constants

PROPEL_ATTR_CACHE_PREPARES

Attribute to use to set whether to cache prepared statements.

DEFAULT_SLOW_THRESHOLD

DEFAULT_ONLYSLOW_ENABLED

Properties

boolean $useDebug

Methods

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

Creates a PropelPDO instance representing a connection to a database.

from PropelPDO
setConfiguration(PropelConfiguration $configuration)

Inject the runtime configuration

from PropelPDO
PropelConfiguration getConfiguration()

Get the runtime configuration

from PropelPDO
integer getNestedTransactionCount()

Gets the current transaction depth.

from PropelPDO
boolean isInTransaction()

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

from PropelPDO
boolean isCommitable()

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

from PropelPDO
boolean beginTransaction()

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

from PropelPDO
boolean commit()

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

from PropelPDO
boolean rollBack()

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

from PropelPDO
boolean forceRollBack()

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

from PropelPDO
setAttribute(integer $attribute, mixed $value)

Sets a connection attribute.

from PropelPDO
mixed getAttribute(integer $attribute)

Gets a connection attribute.

from PropelPDO
PDOStatement prepare(string $sql, array $driver_options = array())

Prepares a statement for execution and returns a statement object.

from PropelPDO
integer exec(string $sql)

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

from PropelPDO
PDOStatement query()

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

from PropelPDO
clearStatementCache()

Clears any stored prepared statements for this connection.

from PropelPDO
integer getQueryCount()

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

from PropelPDO
integer incrementQueryCount()

Increments the number of queries performed by this DebugPDO instance.

from PropelPDO
string getLastExecutedQuery()

Get the SQL code for the latest query executed by Propel

from PropelPDO
setLastExecutedQuery(string $query)

Set the SQL code for the latest query executed by Propel

from PropelPDO
useDebug(boolean $value = true)

Enable or disable the query debug features

from PropelPDO
setLogLevel(integer $level)

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

from PropelPDO
setLogger(BasicLogger $logger)

Sets a logger to use.

from PropelPDO
BasicLogger getLogger()

Gets the logger in use.

from PropelPDO
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.

from PropelPDO
array getDebugSnapshot()

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

from PropelPDO
__destruct()

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

from PropelPDO

Details

in PropelPDO at line 134
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.

in PropelPDO at line 153
public setConfiguration(PropelConfiguration $configuration)

Inject the runtime configuration

Parameters

PropelConfiguration $configuration

in PropelPDO at line 163
public PropelConfiguration getConfiguration()

Get the runtime configuration

Return Value

PropelConfiguration

in PropelPDO at line 176
public integer getNestedTransactionCount()

Gets the current transaction depth.

Return Value

integer

in PropelPDO at line 196
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

in PropelPDO at line 207
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

in PropelPDO at line 217
public boolean beginTransaction()

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

Return Value

boolean

in PropelPDO at line 238
public boolean commit()

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

Return Value

boolean

in PropelPDO at line 267
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.

in PropelPDO at line 294
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.

in PropelPDO at line 323
public 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.

in PropelPDO at line 342
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

in PropelPDO at line 366
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

in PropelPDO at line 397
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

in PropelPDO at line 424
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.

in PropelPDO at line 450
public clearStatementCache()

Clears any stored prepared statements for this connection.

in PropelPDO at line 482
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).

in PropelPDO at line 498
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

in PropelPDO at line 508
public string getLastExecutedQuery()

Get the SQL code for the latest query executed by Propel

Return Value

string Executable SQL code

in PropelPDO at line 518
public setLastExecutedQuery(string $query)

Set the SQL code for the latest query executed by Propel

Parameters

string $query Executable SQL code

in PropelPDO at line 528
public useDebug(boolean $value = true)

Enable or disable the query debug features

Parameters

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

in PropelPDO at line 547
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.

in PropelPDO at line 559
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).

in PropelPDO at line 569
public BasicLogger getLogger()

Gets the logger in use.

Return Value

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

in PropelPDO at line 585
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()

in PropelPDO at line 631
public array getDebugSnapshot()

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

Return Value

array

in PropelPDO at line 766
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()