Skip to content

Commit 41d982b

Browse files
tarampampambarryvdh
tarampampam
authored and
barryvdh
committed
Updated/added comments for PDO Collector (php-debugbar#275)
* Update TraceablePDO.php * Update TraceablePDO.php * Update TraceablePDOStatement.php
1 parent e634fbd commit 41d982b

File tree

2 files changed

+170
-44
lines changed

2 files changed

+170
-44
lines changed

‎src/DebugBar/DataCollector/PDO/TraceablePDO.php‎

Lines changed: 118 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,17 @@
44

55
use PDO;
66
use PDOException;
7+
use DebugBar\DataCollector\PDO\TraceablePDOStatement;
78

89
/**
910
* A PDO proxy which traces statements
1011
*/
1112
class TraceablePDO extends PDO
1213
{
14+
/** @var PDO */
1315
protected $pdo;
1416

17+
/** @var array */
1518
protected $executedStatements = array();
1619

1720
public function __construct(PDO $pdo)
@@ -20,78 +23,177 @@ public function __construct(PDO $pdo)
2023
$this->pdo->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('DebugBar\DataCollector\PDO\TraceablePDOStatement', array($this)));
2124
}
2225

26+
/**
27+
* Initiates a transaction
28+
*
29+
* @link http://php.net/manual/en/pdo.begintransaction.php
30+
* @return bool TRUE on success or FALSE on failure.
31+
*/
2332
public function beginTransaction()
2433
{
2534
return $this->pdo->beginTransaction();
2635
}
2736

37+
/**
38+
* Commits a transaction
39+
*
40+
* @link http://php.net/manual/en/pdo.commit.php
41+
* @return bool TRUE on success or FALSE on failure.
42+
*/
2843
public function commit()
2944
{
3045
return $this->pdo->commit();
3146
}
3247

48+
/**
49+
* Fetch extended error information associated with the last operation on the database handle
50+
*
51+
* @link http://php.net/manual/en/pdo.errorinfo.php
52+
* @return array PDO::errorInfo returns an array of error information
53+
*/
3354
public function errorCode()
3455
{
3556
return $this->pdo->errorCode();
3657
}
3758

59+
/**
60+
* Fetch extended error information associated with the last operation on the database handle
61+
*
62+
* @link http://php.net/manual/en/pdo.errorinfo.php
63+
* @return array PDO::errorInfo returns an array of error information
64+
*/
3865
public function errorInfo()
3966
{
4067
return $this->pdo->errorInfo();
4168
}
4269

43-
public function exec($sql)
70+
/**
71+
* Execute an SQL statement and return the number of affected rows
72+
*
73+
* @link http://php.net/manual/en/pdo.exec.php
74+
* @param string $statement
75+
* @return int|bool PDO::exec returns the number of rows that were modified or deleted by the
76+
* SQL statement you issued. If no rows were affected, PDO::exec returns 0. This function may
77+
* return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE.
78+
* Please read the section on Booleans for more information
79+
*/
80+
public function exec($statement)
4481
{
45-
return $this->profileCall('exec', $sql, func_get_args());
82+
return $this->profileCall('exec', $statement, func_get_args());
4683
}
4784

48-
public function getAttribute($attr)
85+
/**
86+
* Retrieve a database connection attribute
87+
*
88+
* @link http://php.net/manual/en/pdo.getattribute.php
89+
* @param int $attribute One of the PDO::ATTR_* constants
90+
* @return mixed A successful call returns the value of the requested PDO attribute.
91+
* An unsuccessful call returns null.
92+
*/
93+
public function getAttribute($attribute)
4994
{
50-
return $this->pdo->getAttribute($attr);
95+
return $this->pdo->getAttribute($attribute);
5196
}
5297

98+
/**
99+
* Checks if inside a transaction
100+
*
101+
* @link http://php.net/manual/en/pdo.intransaction.php
102+
* @return bool TRUE if a transaction is currently active, and FALSE if not.
103+
*/
53104
public function inTransaction()
54105
{
55106
return $this->pdo->inTransaction();
56107
}
57108

109+
/**
110+
* Returns the ID of the last inserted row or sequence value
111+
*
112+
* @link http://php.net/manual/en/pdo.lastinsertid.php
113+
* @param string $name [optional]
114+
* @return string If a sequence name was not specified for the name parameter, PDO::lastInsertId
115+
* returns a string representing the row ID of the last row that was inserted into the database.
116+
*/
58117
public function lastInsertId($name = null)
59118
{
60119
return $this->pdo->lastInsertId($name);
61120
}
62121

63-
public function prepare($sql, $driver_options = array())
122+
/**
123+
* Prepares a statement for execution and returns a statement object
124+
*
125+
* @link http://php.net/manual/en/pdo.prepare.php
126+
* @param string $statement This must be a valid SQL statement template for the target DB server.
127+
* @param array $driver_options [optional] This array holds one or more key=>value pairs to
128+
* set attribute values for the PDOStatement object that this method returns.
129+
* @return TraceablePDOStatement|bool If the database server successfully prepares the statement,
130+
* PDO::prepare returns a PDOStatement object. If the database server cannot successfully prepare
131+
* the statement, PDO::prepare returns FALSE or emits PDOException (depending on error handling).
132+
*/
133+
public function prepare($statement, $driver_options = array())
64134
{
65-
return $this->pdo->prepare($sql, $driver_options);
135+
return $this->pdo->prepare($statement, $driver_options);
66136
}
67137

68-
public function query($sql)
138+
/**
139+
* Executes an SQL statement, returning a result set as a PDOStatement object
140+
*
141+
* @link http://php.net/manual/en/pdo.query.php
142+
* @param string $statement
143+
* @return TraceablePDOStatement|bool PDO::query returns a PDOStatement object, or FALSE on
144+
* failure.
145+
*/
146+
public function query($statement)
69147
{
70-
return $this->profileCall('query', $sql, func_get_args());
148+
return $this->profileCall('query', $statement, func_get_args());
71149
}
72150

73-
public function quote($expr, $parameter_type = PDO::PARAM_STR)
151+
/**
152+
* Quotes a string for use in a query.
153+
*
154+
* @link http://php.net/manual/en/pdo.quote.php
155+
* @param string $string The string to be quoted.
156+
* @param int $parameter_type [optional] Provides a data type hint for drivers that have
157+
* alternate quoting styles.
158+
* @return string|bool A quoted string that is theoretically safe to pass into an SQL statement.
159+
* Returns FALSE if the driver does not support quoting in this way.
160+
*/
161+
public function quote($string, $parameter_type = PDO::PARAM_STR)
74162
{
75-
return $this->pdo->quote($expr, $parameter_type);
163+
return $this->pdo->quote($string, $parameter_type);
76164
}
77165

166+
/**
167+
* Rolls back a transaction
168+
*
169+
* @link http://php.net/manual/en/pdo.rollback.php
170+
* @return bool TRUE on success or FALSE on failure.
171+
*/
78172
public function rollBack()
79173
{
80174
return $this->pdo->rollBack();
81175
}
82176

83-
public function setAttribute($attr, $value)
177+
/**
178+
* Set an attribute
179+
*
180+
* @link http://php.net/manual/en/pdo.setattribute.php
181+
* @param int $attribute
182+
* @param mixed $value
183+
* @return bool TRUE on success or FALSE on failure.
184+
*/
185+
public function setAttribute($attribute, $value)
84186
{
85-
return $this->pdo->setAttribute($attr, $value);
187+
return $this->pdo->setAttribute($attribute, $value);
86188
}
87189

88190
/**
89191
* Profiles a call to a PDO method
90192
*
91-
* @param string $method
92-
* @param string $sql
93-
* @param array $args
94-
* @return mixed The result of the call
193+
* @param string $method
194+
* @param string $sql
195+
* @param array $args
196+
* @return mixed The result of the call
95197
*/
96198
protected function profileCall($method, $sql, array $args)
97199
{

‎src/DebugBar/DataCollector/PDO/TraceablePDOStatement.php‎

Lines changed: 52 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,15 @@
1111
*/
1212
class TraceablePDOStatement extends PDOStatement
1313
{
14+
/** @var PDO */
1415
protected $pdo;
1516

17+
/** @var array */
1618
protected $boundParameters = array();
1719

1820
/**
1921
* TraceablePDOStatement constructor.
22+
*
2023
* @param TraceablePDO $pdo
2124
*/
2225
protected function __construct(TraceablePDO $pdo)
@@ -25,12 +28,16 @@ protected function __construct(TraceablePDO $pdo)
2528
}
2629

2730
/**
28-
* @param mixed $column
29-
* @param mixed $param
30-
* @param null $type
31-
* @param null $maxlen
32-
* @param null $driverdata
33-
* @return mixed
31+
* Bind a column to a PHP variable
32+
*
33+
* @link http://php.net/manual/en/pdostatement.bindcolumn.php
34+
* @param mixed $column Number of the column (1-indexed) or name of the column in the result set
35+
* @param mixed $param Name of the PHP variable to which the column will be bound.
36+
* @param int $type [optional] Data type of the parameter, specified by the PDO::PARAM_*
37+
* constants.
38+
* @param int $maxlen [optional] A hint for pre-allocation.
39+
* @param mixed $driverdata [optional] Optional parameter(s) for the driver.
40+
* @return bool TRUE on success or FALSE on failure.
3441
*/
3542
public function bindColumn($column, &$param, $type = null, $maxlen = null, $driverdata = null)
3643
{
@@ -40,51 +47,68 @@ public function bindColumn($column, &$param, $type = null, $maxlen = null, $driv
4047
}
4148

4249
/**
43-
* @param mixed $param
44-
* @param mixed $var
45-
* @param int $data_type
46-
* @param null $length
47-
* @param null $driver_options
48-
* @return mixed
50+
* Binds a parameter to the specified variable name
51+
*
52+
* @link http://php.net/manual/en/pdostatement.bindparam.php
53+
* @param mixed $parameter Parameter identifier. For a prepared statement using named
54+
* placeholders, this will be a parameter name of the form :name. For a prepared statement using
55+
* question mark placeholders, this will be the 1-indexed position of the parameter.
56+
* @param mixed $variable Name of the PHP variable to bind to the SQL statement parameter.
57+
* @param int $data_type [optional] Explicit data type for the parameter using the PDO::PARAM_*
58+
* constants.
59+
* @param int $length [optional] Length of the data type. To indicate that a parameter is an OUT
60+
* parameter from a stored procedure, you must explicitly set the length.
61+
* @param mixed $driver_options [optional]
62+
* @return bool TRUE on success or FALSE on failure.
4963
*/
50-
public function bindParam($param, &$var, $data_type = PDO::PARAM_STR, $length = null, $driver_options = null)
64+
public function bindParam($parameter, &$variable, $data_type = PDO::PARAM_STR, $length = null, $driver_options = null)
5165
{
52-
$this->boundParameters[$param] = $var;
53-
$args = array_merge(array($param, &$var), array_slice(func_get_args(), 2));
66+
$this->boundParameters[$parameter] = $variable;
67+
$args = array_merge(array($parameter, &$variable), array_slice(func_get_args(), 2));
5468
return call_user_func_array(array("parent", 'bindParam'), $args);
5569
}
5670

5771
/**
58-
* @param mixed $param
59-
* @param mixed $value
60-
* @param int $data_type
61-
* @return mixed
72+
* Binds a value to a parameter
73+
*
74+
* @link http://php.net/manual/en/pdostatement.bindvalue.php
75+
* @param mixed $parameter Parameter identifier. For a prepared statement using named
76+
* placeholders, this will be a parameter name of the form :name. For a prepared statement using
77+
* question mark placeholders, this will be the 1-indexed position of the parameter.
78+
* @param mixed $value The value to bind to the parameter.
79+
* @param int $data_type [optional] Explicit data type for the parameter using the PDO::PARAM_*
80+
* constants.
81+
* @return bool TRUE on success or FALSE on failure.
6282
*/
63-
public function bindValue($param, $value, $data_type = PDO::PARAM_STR)
83+
public function bindValue($parameter, $value, $data_type = PDO::PARAM_STR)
6484
{
65-
$this->boundParameters[$param] = $value;
85+
$this->boundParameters[$parameter] = $value;
6686
return call_user_func_array(array("parent", 'bindValue'), func_get_args());
6787
}
6888

6989
/**
70-
* @param null $params
71-
* @return bool
72-
* @throws null
90+
* Executes a prepared statement
91+
*
92+
* @link http://php.net/manual/en/pdostatement.execute.php
93+
* @param array $input_parameters [optional] An array of values with as many elements as there
94+
* are bound parameters in the SQL statement being executed. All values are treated as
95+
* PDO::PARAM_STR.
96+
* @return bool TRUE on success or FALSE on failure.
7397
*/
74-
public function execute($params = null)
98+
public function execute($input_parameters = null)
7599
{
76100
$preparedId = spl_object_hash($this);
77101
$boundParameters = $this->boundParameters;
78-
if (is_array($params)) {
79-
$boundParameters = array_merge($boundParameters, $params);
102+
if (is_array($input_parameters)) {
103+
$boundParameters = array_merge($boundParameters, $input_parameters);
80104
}
81105

82106
$trace = new TracedStatement($this->queryString, $boundParameters, $preparedId);
83107
$trace->start();
84108

85109
$ex = null;
86110
try {
87-
$result = parent::execute($params);
111+
$result = parent::execute($input_parameters);
88112
} catch (PDOException $e) {
89113
$ex = $e;
90114
}

0 commit comments

Comments
 (0)