construct.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="pdo.construct" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>PDO::__construct</refname>
  <refpurpose>
   Creates a PDO instance representing a connection to a database
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <constructorsynopsis role="PDO">
   <modifier>public</modifier> <methodname>PDO::__construct</methodname>
   <methodparam><type>string</type><parameter>dsn</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
  </constructorsynopsis>
  <para>
   Creates a PDO instance to represent a connection to the requested
   database. 
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>dsn</parameter></term>
     <listitem>
      <para>
       The Data Source Name, or DSN, contains the information required to
       connect to the database.
      </para>
      <para>
       In general, a DSN consists of the PDO driver name, followed by a colon,
       followed by the PDO driver-specific connection syntax. Further
       information is available from the <link linkend="pdo.drivers">PDO
       driver-specific documentation</link>.
      </para>
      <para>
       The <parameter>dsn</parameter> parameter supports three
       different methods of specifying the arguments required to create
       a database connection:
      </para>
      <para>
       <variablelist>
        <varlistentry><term>Driver invocation</term>
         <listitem>
          <para>
           <parameter>dsn</parameter> contains the full DSN.
          </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>
          <para><userinput>uri:file:///path/to/dsnfile</userinput></para>
         </listitem>
        </varlistentry>
        <varlistentry><term>Aliasing</term>
         <listitem>
          <para>
           <parameter>dsn</parameter> consists of a name 
           <parameter>name</parameter> that maps to 
           <code>pdo.dsn.<parameter>name</parameter></code> in &php.ini;
           defining the DSN string.
          </para>
          <note>
           <para>
            The alias must be defined in &php.ini;, and not &htaccess; or &httpd.conf;
           </para>
          </note>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>username</parameter></term>
     <listitem>
      <para>
       The user name for the DSN string. This parameter is optional for
       some PDO drivers.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>password</parameter></term>
     <listitem>
      <para>
       The password for the DSN string. This parameter is optional for
       some PDO drivers.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       A key=&gt;value array of driver-specific connection options.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   <methodname>PDO::__construct</methodname> throws a <classname>PDOException</classname> if the attempt
   to connect to the requested database fails, regardless of which <constant>PDO::ATTR_ERRMODE</constant> is currently set.
  </para>
 </refsect1>

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

$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';

$dbh = new PDO($dsn, $user, $password);

?>
]]>
    </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>
    <screen>
<![CDATA[
odbc:DSN=SAMPLE;UID=john;PWD=mypass
]]>
    </screen>
    <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

$dsn = 'uri:file:///usr/local/dbconnect';
$user = '';
$password = '';

$dbh = new PDO($dsn, $user, $password);

?>
]]>
    </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>:
    </para>
    <programlisting role="ini">
[PDO]
pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"
    </programlisting>
    <programlisting role="php">
<![CDATA[
<?php

$dsn = 'mydb';
$user = '';
$password = '';

$dbh = new PDO($dsn, $user, $password);

?>
]]>
    </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:"~/.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
-->