<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.6 $ -->
  <refentry id="function.PDO-construct">
   <refnamediv>
    <refname>PDO::__construct</refname>
    <refpurpose>
     Creates a PDO instance representing a connection to a database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <methodsynopsis>
     <type>PDO</type><methodname>PDO::__construct</methodname>
     <methodparam><type>string</type><parameter>dsn</parameter></methodparam>
     <methodparam><type>string</type><parameter>username</parameter></methodparam>
     <methodparam><type>string</type><parameter>password</parameter></methodparam>
     <methodparam choice="opt"><type>array</type><parameter>driver_opts</parameter></methodparam>
    </methodsynopsis>
    &warn.experimental.func;
    <para>
     Creates a PDO instance to represent a connection to the requested
     database. 
    </para>
   </refsect1>
   <refsect1 role="parameters">
    &reftitle.parameters;
    <para>
     <variablelist>
      <varlistentry><term>dsn</term>
       <listitem>
        <para>
         The <parameter>dsn</parameter> parameter supports three
         different methods of specifying the arguments required to create
         a database connection:
         <variablelist>
          <varlistentry><term>Driver invocation</term>
           <listitem>
            <para>
             <parameter>dsn</parameter> consists of the PDO driver name, followed
             by a colon, followed by the PDO driver-specific connection syntax.
             For example, <userinput>'odbc:DSN=SAMPLE;UID=db2inst1;PWD=ibmdb2'</userinput>
             would create a PDO_ODBC connection to an ODBC database, while
             <userinput>'mysql:host=127.0.0.1;dbname=testdb'</userinput> would create
             a PDO_MYSQL connection to a MySQL database.
            </para>
           </listitem>
          </varlistentry>
          <varlistentry><term>URI invocation</term>
           <listitem>
            <para>
             <parameter>dsn</parameter> consists of <userinput>uri:</userinput>
             followed by a URI that defines the location of a file containing
             the DSN string. The URI can specify a local file or a remote URL.
            </para>
           </listitem>
          </varlistentry>
          <varlistentry><term>Aliasing</term>
           <listitem>
            <para>
             <parameter>dsn</parameter> consists of a name 
             <parameter>name</parameter> that maps to 
             <literal>pdo.dsn.<parameter>name</parameter></literal> in &php.ini;
             defining the DSN string. <parameter>name</parameter> can not contain
             a colon.
            </para>
           </listitem>
          </varlistentry>
         </variablelist>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry><term>username</term>
       <listitem>
        <para>
         The user name, if required, for the DSN string.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry><term>password</term>
       <listitem>
        <para>
         The password, if required, for the DSN string.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry><term>driver_opts</term>
       <listitem>
        <para>
         A key =&gt; value array of driver-specific connection options.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </refsect1>

   <refsect1 role="returnvalues">
    &reftitle.returnvalues;
    <para>
     Returns a PDO object on success.
    </para>
   </refsect1>

   <refsect1 role="exceptions">
    &reftitle.exceptions;
    <para>
     <function>PDO::construct</function> throws a PDOException if the attempt
     to connect to the requested database fails.
    </para>
   </refsect1>

   <refsect1 role="examples">
    &reftitle.examples;
    <para>
     <example><title>Create a PDO instance via driver invocation</title>
      <programlisting role="php">
<![CDATA[
<?php
/* Connect to an ODBC database using driver invocation */

$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';
try {
  $dbh = new PDO($dsn, $user, $password);
}
catch (PDOException $e) {
  echo 'Connection failed: ' . $e->getMessage();
}
?>
]]>
      </programlisting>
     </example>
     <example><title>Create a PDO instance via URI invocation</title>
      <para>
       The following example assumes that the file
       <filename>/usr/local/dbconnect</filename> exists with file permissions
       that enable PHP to read the file. The file contains the PDO DSN to
       connect to a DB2 database through the PDO_ODBC driver:
      </para>
      <programlisting>
<![CDATA[
odbc:DSN=SAMPLE;UID=db2inst1;PWD=password
]]>
      </programlisting>
      <para>
       The PHP script can then create a database connection by simply
       passing the <literal>uri:</literal> parameter and pointing to
       the file URI:
      </para>
      <programlisting role="php">
<![CDATA[
<?php
/* Connect to an ODBC database using driver invocation */

$dsn = 'uri:file:///usr/local/dbconnect';
$user = '';
$password = '';
try {
  $dbh = new PDO($dsn, $user, $password);
}
catch (PDOException $e) {
  echo 'Connection failed: ' . $e->getMessage();
}
?>
]]>
      </programlisting>
     </example>
     <example><title>Create a PDO instance using an alias</title>
      <para>
       The following example assumes that &php.ini; contains the following
       entry to enable a connection to a MySQL database using only the
       alias <literal>mydb</literal>:
       <screen>pdo.dsn.mydb=mysql:dbname=testdb;host=127.0.0.1</screen>
      </para>
      <programlisting role="php">
<![CDATA[
<?php
/* Connect to an ODBC database using an alias */

$dsn = 'mydb';
$user = '';
$password = '';
try {
  $dbh = new PDO($dsn, $user, $password);
}
catch (PDOException $e) {
  echo 'Connection failed: ' . $e->getMessage();
}
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

<!-- 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:"../../../../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
-->