Class: DebugPDO

Source Location: /util/DebugPDO.php

Class Overview

PDO
   |
   --PropelPDO
      |
      --DebugPDO

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

Author(s):

Francois Zaninotto
Cameron Brunner <cameron.brunner@gmail.com>
Hans Lellelid <hans@xmpl.org>
Jarno Rantanen <jarno.rantanen@tkk.fi>
Christian Abegg <abegg.ch@gmail.com>

Child classes:

MssqlDebugPDO: dblib doesn't support transactions so we need to add a workaround for transactions, last insert ID, and quoting

Inherited Constants

Class: PropelPDO

PropelPDO::PROPEL_ATTR_CACHE_PREPARES

Inherited Variables

Class: PropelPDO

PropelPDO::$cachePreparedStatements
PropelPDO::$isUncommitable
PropelPDO::$nestedTransactionCount
PropelPDO::$preparedStatements

Inherited Methods

Class: PropelPDO

PropelPDO::beginTransaction(): Overrides PDO::beginTransaction() to prevent errors due to already-in-progress transaction.
PropelPDO::clearStatementCache(): Clears any stored prepared statements for this connection.
PropelPDO::commit(): Overrides PDO::commit() to only commit the transaction if we are in the outermost transaction nesting level.
PropelPDO::decrementNestedTransactionCount(): Decrements the current transaction depth by one.
PropelPDO::forceRollBack(): Rollback the whole transaction, even if this is a nested rollback and reset the nested transaction count to 0.
PropelPDO::getAttribute(): Gets a connection attribute.
PropelPDO::getNestedTransactionCount(): Gets the current transaction depth.
PropelPDO::incrementNestedTransactionCount(): Increments the current transaction depth by one.
PropelPDO::isInTransaction(): Is this PDO connection currently in-transaction? This is equivalent to asking whether the current nested transaction count is greater than 0.
PropelPDO::prepare(): Overrides PDO::prepare() to add query caching support if the PropelPDO::PROPEL_ATTR_CACHE_PREPARES was set to true.
PropelPDO::rollBack(): Overrides PDO::rollBack() to only rollback the transaction if we are in the outermost
PropelPDO::setAttribute(): Sets a connection attribute.
PropelPDO::setNestedTransactionCount(): Set the current transaction depth.

Class Details

[line 119]
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.enabled (default: true) Should any logging take place

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.

Tags:

author:	Francois Zaninotto
author:	Cameron Brunner <cameron.brunner@gmail.com>
author:	Hans Lellelid <hans@xmpl.org>
author:	Jarno Rantanen <jarno.rantanen@tkk.fi>
author:	Christian Abegg <abegg.ch@gmail.com>
since:	2006-09-22
example:	example not found

[ Top ]

Class Variables

static $defaultLogMethods = array(
      'DebugPDO::exec',
      'DebugPDO::query',
      'DebugPDOStatement::execute',
   )

[line 164]

The default value for runtime config item "debugpdo.logging.methods".

Tags:

access:

protected

Type:

array

[ Top ]

$lastExecutedQuery =

[line 136]

SQL code of the latest performed query.

Tags:

access:

protected

Type:

string

[ Top ]

$logger =

[line 150]

Configured BasicLogger (or compatible) logger.

Tags:

access:

protected

Type:

BasicLogger

[ Top ]

$queryCount = 0

[line 129]

Count of queries performed.

Tags:

access:

protected

Type:

int

[ Top ]

$statementClass = 'DebugPDOStatement'

[line 143]

The statement class to use.

Tags:

access:

protected

Type:

string

[ Top ]

Class Methods

constructor __construct [line 181]

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

Creates a DebugPDO instance representing a connection to a database.

This method is overridden in order to specify a custom PDOStatement class and to implement logging.

Tags:

throws:	PDOException if there is an error during connection initialization.
access:	public

Parameters:

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

[ Top ]

destructor __destruct [line 545]

void __destruct(
)

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

Tags:

see:	self::log()
access:	public

[ Top ]

method configureStatementClass [line 197]

void configureStatementClass(
[boolean
$suppressError = false])

Configures the PDOStatement class for this connection.

Tags:

throws:	PropelException if the statement class cannot be set (and $suppressError is false).
access:	protected

Parameters:

boolean

$suppressError

Whether to suppress an exception if the statement class cannot be set.

[ Top ]

method exec [line 309]

int exec(

$sql)

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

Overridden for query counting and logging.

Tags:

access:

public

Parameters:

$sql

[ Top ]

method getDebugSnapshot [line 422]

array getDebugSnapshot(
)

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

Tags:

access:

public

[ Top ]

method getLastExecutedQuery [line 268]

string getLastExecutedQuery(
)

Get the SQL code for the latest query executed by Propel

Tags:

return:	Executable SQL code
access:	public

[ Top ]

method getLoggingConfig [line 440]

mixed getLoggingConfig(
string
$key, mixed
$defaultValue)

Returns a named configuration item from the Propel runtime configuration, from under the 'debugpdo.logging' prefix. If such a configuration setting hasn't been set, the given default value will be returned.

Tags:

access:

protected

Parameters:

string	$key	Key for which to return the value.
mixed	$defaultValue	Default value to apply if config item hasn't been set.

[ Top ]

method getLogPrefix [line 458]

string getLogPrefix(
string
$methodName, array
$debugSnapshot)

Returns a prefix that may be prepended to a log line, containing debug information according to the current configuration.

Uses a given $debugSnapshot to calculate how much time has passed since the call to self::getDebugSnapshot(), how much the memory consumption by PHP has changed etc.

Tags:

see:	self::getDebugSnapshot()
access:	protected

Parameters:

string	$methodName	Name of the method whose execution is being logged.
array	$debugSnapshot	A previous return value from self::getDebugSnapshot().

[ Top ]

method getQueryCount [line 240]

int 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.

Tags:

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

[ Top ]

method getReadableBytes [line 529]

string getReadableBytes(
int
$bytes, int
$precision)

Returns a human-readable representation of the given byte count.

Tags:

access:

protected

Parameters:

int	$bytes	Byte count to convert.
int	$precision	How many decimals to include.

[ Top ]

method getStatementClass [line 226]

string getStatementClass(
)

Gets the custom classname to use for PDOStatement.

Tags:

access:

public

[ Top ]

method incrementQueryCount [line 258]

int 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).

Tags:

access:

public

[ Top ]

method log [line 381]

void log(
string
$msg, [int
$level = null], [string
$methodName = null], [
$debugSnapshot = null])

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

Tags:

see:	self::setLogger()
access:	public
uses:	self::getLogPrefix()

Parameters:

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

[ Top ]

method prepare [line 292]

PDOStatement prepare(
string
$sql, [array
$driver_options = array()])

Prepares a statement for execution and returns a statement object.

Overrides PDO::prepare() to add logging and query counting.

Tags:

access:

public

Overrides PropelPDO::prepare() (Overrides PDO::prepare() to 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 or more key=>value pairs to set attribute values for the PDOStatement object that this method returns.

[ Top ]

method query [line 330]

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.

Overridden for query counting and logging.

Tags:

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

[ Top ]

method setLastExecutedQuery [line 278]

void setLastExecutedQuery(
string
$query)

Set the SQL code for the latest query executed by Propel

Tags:

access:

public

Parameters:

string

$query

Executable SQL code

[ Top ]

method setLogger [line 365]

void setLogger(
BasicLogger
$logger)

Sets a logger to use.

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

Tags:

access:

public

Parameters:

BasicLogger

$logger

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

[ Top ]

method setLogLevel [line 353]

void setLogLevel(
int
$level)

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

Tags:

access:

public

Parameters:

int

$level

Value of one of the Propel::LOG_* class constants.

[ Top ]

method setStatementClass [line 215]

void setStatementClass(
string
$classname)

Sets the custom classname to use for PDOStatement.

It is assumed that the specified classname has been loaded (or can be loaded on-demand with autoload).

Tags:

access:

public

Parameters:

string

$classname

Name of the statement class to use.

[ Top ]

Class Constants

DEFAULT_ONLYSLOW_ENABLED = false

[line 122]

[ Top ]

DEFAULT_SLOW_THRESHOLD = 0.1

[line 121]

[ Top ]

Documentation generated on Tue, 12 Jan 2010 23:08:06 +0000 by phpDocumentor 1.4.3

Class: DebugPDO

Class Overview

Author(s):

Variables

Constants

Methods

Child classes:

Inherited Constants

Class: PropelPDO

Inherited Variables

Class: PropelPDO

Inherited Methods

Class: PropelPDO

Class Details

Tags:

Class Variables

static $defaultLogMethods = array( 'DebugPDO::exec', 'DebugPDO::query', 'DebugPDOStatement::execute', )

Tags:

$lastExecutedQuery =

Tags:

$logger =

Tags:

$queryCount = 0

Tags:

$statementClass = 'DebugPDOStatement'

Tags:

Class Methods

constructor __construct [line 181]

Tags:

Parameters:

destructor __destruct [line 545]

Tags:

method configureStatementClass [line 197]

Tags:

Parameters:

method exec [line 309]

Tags:

Parameters:

method getDebugSnapshot [line 422]

Tags:

method getLastExecutedQuery [line 268]

Tags:

method getLoggingConfig [line 440]

Tags:

Parameters:

method getLogPrefix [line 458]

Tags:

Parameters:

method getQueryCount [line 240]

Tags:

method getReadableBytes [line 529]

Tags:

Parameters:

method getStatementClass [line 226]

Tags:

method incrementQueryCount [line 258]

Tags:

method log [line 381]

Tags:

Parameters:

method prepare [line 292]

Tags:

Parameters:

method query [line 330]

Tags:

method setLastExecutedQuery [line 278]

Tags:

Parameters:

method setLogger [line 365]

Tags:

Parameters:

method setLogLevel [line 353]

Tags:

Parameters:

method setStatementClass [line 215]

Tags:

Parameters:

Class Constants

DEFAULT_ONLYSLOW_ENABLED = false

DEFAULT_SLOW_THRESHOLD = 0.1

static $defaultLogMethods = array(
'DebugPDO::exec',
'DebugPDO::query',
'DebugPDOStatement::execute',
)