reference/pdo/connections.xml
d861a1bcea24f05e52e4938c1ecdf9d70326d7aa
d861a1bcea24f05e52e4938c1ecdf9d70326d7aa
...
...
@@ -36,28 +36,24 @@ $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
36
36
<?php
37
37
try {
38
38
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
39
-
foreach($dbh->query('SELECT * from FOO') as $row) {
40
-
print_r($row);
41
-
}
42
-
$dbh = null;
43
39
} catch (PDOException $e) {
44
-
print "Error!: " . $e->getMessage() . "<br/>";
45
-
die();
40
+
// attempt to retry the connection after some timeout for example
46
41
}
47
-
?>
48
42
]]>
49
43
</programlisting>
50
44
</example>
51
45
</para>
52
46
<warning>
53
47
<para>
54
-
If your application does not catch the exception thrown from the PDO
55
-
constructor, the default action taken by the zend engine is to terminate
56
-
the script and display a back trace. This back trace will likely reveal
57
-
the full database connection details, including the username and
58
-
password. It is your responsibility to catch this exception, either
59
-
explicitly (via a <literal>catch</literal> statement) or implicitly via
60
-
<function>set_exception_handler</function>.
48
+
Just like any other <link linkend="language.exceptions">exception</link>,
49
+
<classname>PDOException</classname> could be caught either explicitly, via
50
+
a &catch; statement, or implicitly via <function>set_exception_handler</function>.
51
+
Otherwise, the default behaviour of converting an uncaught exception to a
52
+
<constant>E_FATAL_ERROR</constant> will occur.
53
+
The fatal error will contain a backtrace that can leak connection details.
54
+
As such, the &php.ini; option
55
+
<link linkend="ini.display-errors"><literal>display_errors</literal></link>
56
+
should be set to <literal>0</literal> on a production server.
61
57
</para>
62
58
</warning>
63
59
<para>
...
...
@@ -65,10 +61,18 @@ try {
65
61
is returned to your script. The connection remains active for the
66
62
lifetime of that PDO object. To close the connection, you need to
67
63
destroy the object by ensuring that all remaining references to it are
68
-
deleted--you do this by assigning &null; to the variable that holds the
64
+
deleted—you do this by assigning &null; to the variable that holds the
69
65
object. If you don't do this explicitly, PHP will automatically close
70
66
the connection when your script ends.
71
67
</para>
68
+
<note>
69
+
<simpara>
70
+
If there are still other references to this PDO instance (such as from a
71
+
PDOStatement instance, or from other variables referencing the same PDO
72
+
instance), these have to be removed also (for instance, by assigning &null; to
73
+
the variable that references the PDOStatement).
74
+
</simpara>
75
+
</note>
72
76
<para>
73
77
<example>
74
78
<title>Closing a connection</title>
...
...
@@ -77,9 +81,10 @@ try {
77
81
<?php
78
82
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
79
83
// use the connection here
80
-
84
+
$sth = $dbh->query('SELECT * FROM foo');
81
85
82
86
// and now we're done; close it
87
+
$sth = null;
83
88
$dbh = null;
84
89
?>
85
90
]]>
...
...
@@ -109,12 +114,19 @@ $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
109
114
</programlisting>
110
115
</example>
111
116
</para>
117
+
<para>
118
+
The value of the <constant>PDO::ATTR_PERSISTENT</constant> option is converted
119
+
to &boolean; (enable/disable persistent connections), unless it is a non-numeric
120
+
&string;, in which case it allows to use multiple persistent connection pools.
121
+
This is useful if different connections use incompatible settings, for instance,
122
+
different values of <constant>PDO::MYSQL_ATTR_USE_BUFFERED_QUERY</constant>.
123
+
</para>
112
124
<note>
113
125
<para>
114
126
If you wish to use persistent connections, you must set
115
127
<constant>PDO::ATTR_PERSISTENT</constant> in the array of driver options
116
128
passed to the PDO constructor. If setting this attribute with
117
-
<function>PDO::setAttribute</function> after instantiation of the
129
+
<methodname>PDO::setAttribute</methodname> after instantiation of the
118
130
object, the driver will not use persistent connections.
119
131
</para>
120
132
</note>
121
133