<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<chapter xml:id="pdo.connections" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Connections and Connection management</title>
 <para>
  Connections are established by creating instances of the PDO base class.
  It doesn't matter which driver you want to use; you always use the PDO
  class name. The constructor accepts parameters for specifying the
  database source (known as the DSN) and optionally for the username and
  password (if any).
 </para>
 <para>
  <example>
   <title>Connecting to MySQL</title>
   <programlisting role="php">
<![CDATA[
<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
?>
]]> 
   </programlisting>
  </example>
 </para>
 <para>
  If there are any connection errors, a <literal>PDOException</literal>
  object will be thrown.  You may catch the exception if you want to handle
  the error condition, or you may opt to leave it for an application
  global exception handler that you set up via
  <function>set_exception_handler</function>.
 </para>
 <para>
  <example><title>Handling connection errors</title>
   <programlisting role="php">
<![CDATA[
<?php
try {
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
} catch (PDOException $e) {
    // attempt to retry the connection after some timeout for example
}
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <para>
   Just like any other <link linkend="language.exceptions">exception</link>,
   <classname>PDOException</classname> could be caught either explicitly, via
   a &catch; statement, or implicitly via <function>set_exception_handler</function>.
   Otherwise, the default behaviour of converting an uncaught exception to a
   <constant>E_FATAL_ERROR</constant> will occur.
   The fatal error will contain a backtrace that can leak connection details.
   As such, the &php.ini; option
   <link linkend="ini.display-errors"><literal>display_errors</literal></link>
   should be set to <literal>0</literal> on a production server.
  </para>
 </warning>
 <para>
  Upon successful connection to the database, an instance of the PDO class
  is returned to your script.  The connection remains active for the
  lifetime of that PDO object.  To close the connection, you need to
  destroy the object by ensuring that all remaining references to it are
  deleted—you do this by assigning &null; to the variable that holds the
  object.  If you don't do this explicitly, PHP will automatically close
  the connection when your script ends.
 </para>
 <note>
  <simpara>
   If there are still other references to this PDO instance (such as from a
   PDOStatement instance, or from other variables referencing the same PDO
   instance), these have to be removed also (for instance, by assigning &null; to
   the variable that references the PDOStatement).
  </simpara>
 </note>
 <para>
  <example>
   <title>Closing a connection</title>
   <programlisting role="php">
<![CDATA[
<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
// use the connection here
$sth = $dbh->query('SELECT * FROM foo');

// and now we're done; close it
$sth = null;
$dbh = null;
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  Many web applications will benefit from making persistent connections to
  database servers.  Persistent connections are not closed at the end of the
  script, but are cached and re-used when another script requests a
  connection using the same credentials.  The persistent connection cache
  allows you to avoid the overhead of establishing a new connection every
  time a script needs to talk to a database, resulting in a faster web
  application.
 </para>
 <para>
  <example>
   <title>Persistent connections</title>
   <programlisting role="php">
<![CDATA[
<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
    PDO::ATTR_PERSISTENT => true
));
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  The value of the <constant>PDO::ATTR_PERSISTENT</constant> option is converted
  to &boolean; (enable/disable persistent connections), unless it is a non-numeric
  &string;, in which case it allows to use multiple persistent connection pools.
  This is useful if different connections use incompatible settings, for instance,
  different values of <constant>PDO::MYSQL_ATTR_USE_BUFFERED_QUERY</constant>.
 </para>
 <note>
  <para>
   If you wish to use persistent connections, you must set
   <constant>PDO::ATTR_PERSISTENT</constant> in the array of driver options
   passed to the PDO constructor. If setting this attribute with
   <methodname>PDO::setAttribute</methodname> after instantiation of the
   object, the driver will not use persistent connections.
  </para>
 </note>
 <note>
  <para>
   If you're using the PDO ODBC driver and your ODBC libraries support ODBC
   Connection Pooling (unixODBC and Windows are two that do; there may be
   more), then it's recommended that you don't use persistent PDO
   connections, and instead leave the connection caching to the ODBC
   Connection Pooling layer.  The ODBC Connection Pool is shared with other
   modules in the process; if PDO is told to cache the connection, then
   that connection would never be returned to the ODBC connection pool,
   resulting in additional connections being created to service those other
   modules.
  </para>
 </note>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->