<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="mysqli.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

&reftitle.install;

 <para>
  The <literal>mysqli</literal> extension was introduced with PHP version 
  5.0.0. The MySQL Native Driver was included in PHP version 5.3.0.
 </para>

 <section xml:id="mysqli.installation.linux">

  <title>Installation on Linux</title>

  <para>
   The common Unix distributions include binary versions of PHP that can
   be installed. Although these binary versions are typically built with
   support for MySQL extensions enabled, the extension libraries
   themselves may need to be installed using an additional package. Check
   the package manager than comes with your chosen distribution for
   availability.
  </para>

  <para>
   Unless your Unix distribution comes with a binary package of PHP with
   the <literal>mysqli</literal> extension available, you will need to
   build PHP from source code. Building PHP from source allows you to
   specify the MySQL extensions you want to use, as well as your choice
   of client library for each extension.
  </para>

  <section>

   <title>PHP 5.0, 5.1, 5.2</title>

   <para>
    If building from source code, to ensure that the <literal>mysqli</literal> 
    extension for PHP is enabled, you will need to configure the PHP source code to use
    <literal>mysqli</literal>. This is achieved by running the
    <command>configure</command> script with the option
    <option role="configure">--with-mysqli=mysql_config_path/mysql_config</option>,
    prior to building PHP. This will enable <literal>mysqli</literal> and
    it will use the MySQL Client Library (libmysql) to communicate with
    the MySQL Server.
   </para>

   <para>
    The <literal>mysql_config_path</literal> represents the location of
    the <literal>mysql_config</literal> program that comes with MySQL
    Server.
   </para>

  </section>

  <section>
   
   <title>PHP 5.3.0+</title>

    <para>
     With versions of PHP 5.3.0 and newer, <literal>mysqli</literal> uses 
     MySQL Native Driver by default. This gives a number of benefits over 
     <literal>libmysql</literal>.
    </para>

    <para>
     This is the recommended option, as using the MySQL Native Driver
     results in improved performance and gives access to features not
     available when using the MySQL Client Library. Refer to
     <link linkend="mysqli.overview.mysqlnd">What is PHP's MySQL Native
     Driver?</link> for a brief overview of the advantages of MySQL Native
     Driver.
    </para>

    <para>
     To use MySQL Native Driver with <literal>mysqli</literal> you need to
     configure the PHP source code using the
     <option role="configure">--with-mysqli=mysqlnd</option> option, prior
     to building PHP.
    </para>

    <para>
     Note that it is possible to freely mix MySQL extensions and client
     libraries. For example, it is possible to enable the MySQL extension
     to use the MySQL Client Library (libmysql), while configuring the
     <literal>mysqli</literal> extension to use the MySQL Native Driver.
     However, all permutations of extension and client library are
     possible.
    </para>

    <para>
     The following example builds the MySQL extension to use the MySQL
     Client Library, and the <literal>mysqli</literal> and PDO MYSQL
     extensions to use the MySQL Native Driver:
    </para>

<programlisting role="shell">
./configure --with-mysql=/usr/bin/mysql_config  \
--with-mysqli=mysqlnd \
--with-pdo-mysql=mysqlnd
[other options]
</programlisting>

  </section>

 </section>

 <section xml:id="mysqli.installation.windows">

  <title>Installation on Windows Systems</title>

  <para>
   On Windows, PHP is most commonly installed using the binary
   installer. 
  </para>

  <section>

   <title>PHP 5.0, 5.1, 5.2</title>

   <para>
    Once PHP has been installed, some configuration is
    required to enable <literal>mysqli</literal> and specify the client
    library you want it to use.
   </para>

   <para>
    The <literal>mysqli</literal> extension is not
    enabled by default, so the <filename>php_mysqli.dll</filename> DLL
    must be enabled inside of &php.ini;. In order to do this you need to
    find the &php.ini; file (typically located in
    <filename>c:\php</filename>), and make sure you remove the comment
    (semi-colon) from the start of the line
    <literal>extension=php_mysqli.dll</literal>, in the section marked
    <literal>[PHP_MYSQLI]</literal>.
   </para>

   <para>
    Also, if you want to use the MySQL Client Library with
    <literal>mysqli</literal>, you need to make sure PHP can access the
    client library file. The MySQL Client Library is included as a file
    named <filename>libmysql.dll</filename> in the Windows PHP
    distribution. This file needs to be available in the Windows system's
    <envar>PATH</envar> environment variable, so that it can be
    successfully loaded. See the FAQ titled
    "<link linkend="faq.installation.addtopath">How do I add my PHP
    directory to the PATH on Windows</link>" for information on how to do
    this. Copying <filename>libmysql.dll</filename> to the Windows system
    directory (typically <filename>c:\Windows\system</filename>) also
    works, as the system directory is by default in the system's
    <envar>PATH</envar>. However, this practice is strongly discouraged.
   </para>

   <para>
    As with enabling any PHP extension (such as
    <filename>php_mysqli.dll</filename>), the PHP directive
    <link linkend="ini.extension-dir">extension_dir</link> should be set
    to the directory where the PHP extensions are located. See also the
    <link linkend="install.windows.manual">Manual Windows Installation
    Instructions</link>. An example <literal>extension_dir</literal>
    value for PHP 5 is <filename>c:\php\ext</filename>.
   </para>

   <note>
    <para>
     If when starting the web server an error similar to the following
     occurs: <literal>"Unable to load dynamic library
     './php_mysqli.dll'"</literal>, this is because
     <filename>php_mysqli.dll</filename> and/or
     <filename>libmysql.dll</filename> cannot be found by the system.
    </para>
   </note>
  </section>

  <section>

    <title>PHP 5.3.0+</title>

   <para>
    On Windows, for PHP versions 5.3 and newer, the
    <literal>mysqli</literal> extension is enabled and 
    uses the MySQL Native Driver by default. This means you don't need to 
    worry about configuring access
    to <filename>libmysql.dll</filename>.
   </para>

  </section>

 </section>

</section>
<!-- 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
-->