php-doc-en/reference/mysqli/functions/mysqli-connect.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
  <refentry id="function.mysqli-connect">
   <refnamediv>
    <refname>mysqli_connect</refname>
    <refname>mysqli()</refname>
    <refpurpose>Open a new connection to the MySQL server</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <para>Procedural style</para>
    <methodsynopsis>
     <type>object</type><methodname>mysqli_connect</methodname>
     <methodparam choice='opt'><type>string</type><parameter>host</parameter></methodparam>
     <methodparam choice='opt'><type>string</type><parameter>username</parameter></methodparam>
     <methodparam choice='opt'><type>string</type><parameter>passwd</parameter></methodparam>
     <methodparam choice='opt'><type>string</type><parameter>dbname</parameter></methodparam>
     <methodparam choice='opt'><type>int</type><parameter>port</parameter></methodparam>
     <methodparam choice='opt'><type>string</type><parameter>socket</parameter></methodparam>
    </methodsynopsis>
    <para>Object oriented style (constructor):</para>
    <classsynopsis>
    <ooclass><classname>mysqli</classname></ooclass>
     <constructorsynopsis>
      <methodname>__construct</methodname>
      <methodparam choice='opt'><type>string</type><parameter>host</parameter></methodparam>
      <methodparam choice='opt'><type>string</type><parameter>username</parameter></methodparam>
      <methodparam choice='opt'><type>string</type><parameter>passwd</parameter></methodparam>
      <methodparam choice='opt'><type>string</type><parameter>dbname</parameter></methodparam>
      <methodparam choice='opt'><type>int</type><parameter>port</parameter></methodparam>
      <methodparam choice='opt'><type>string</type><parameter>socket</parameter></methodparam>
     </constructorsynopsis> 
    </classsynopsis>
    <para>
     The <function>mysqli_connect</function> function attempts to open a connection to the MySQL Server 
     running on <parameter>host</parameter> which can be either a host name or an IP address. Passing the
     &null; value or the string "localhost" to this parameter, the local host is assumed. When possible, 
     pipes will be used instead of the TCP/IP protocol. If successful, the <function>mysqli_connect</function>
     will return an object representing the connection to the database, or &false; on failure.
    </para>
    <para>
     The <parameter>username</parameter> and <parameter>password</parameter> parameters specify the
     username and password under which to connect to the MySQL server. If the password is not provided
     (the &null; value is passed), the MySQL server will attempt to authenticate the user against those
     user records which have no password only. This allows one username to be used with different
     permissions (depending on if a password as provided or not).
    </para>
    <para>
     The <parameter>dbname</parameter> parameter if provided will specify the default database to be
     used when performing queries. 
    </para>
    <para>
     The <parameter>port</parameter> and <parameter>socket</parameter> parameters are used in
     conjunction with the <parameter>host</parameter> parameter to further control how to connect
     to the database server. The <parameter>port</parameter> parameter specifies the port number to
     attempt to connect to the MySQL server on, while the <parameter>socket</parameter> parameter
     specifies the socket or named pipe that should be used. 
    </para>
    <note>
     <para>
      Specifying the <parameter>socket</parameter> parameter will not explicitly determine the type
      of connection to be used when connecting to the MySQL server. How the connection is made to the
      MySQL database is determined by the <parameter>host</parameter> parameter.
     </para>
    </note>
   </refsect1>
   <refsect1>
    <title>Return values</title>
    <para>
     Returns a object which represents the connection to a MySQL Server or
     &false; if the connection failed.
    </para>
   </refsect1>
   <refsect1>
    <title>Example</title>
    <example>
     <title>Object oriented style</title>
     <programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* check connection */ 
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

printf("Host information: %s\n", $mysqli->host_info);

/* close connection */
$mysqli->close();
?>
]]>
    </programlisting>
    </example>
    <example>
     <title>Procedural style</title>
     <programlisting role="php">
<![CDATA[
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* check connection */ 
if (!$link) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

printf("Host information: %s\n", mysqli_get_host_info($link));

/* close connection */
mysqli_close($link);
?>
]]>
     </programlisting>
    </example>
    <para>
     The above examples would produce the following output:
    </para>
    <screen>
<![CDATA[
Host information: Localhost via UNIX socket
]]>
    </screen>
   </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
-->