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

 <para xml:id="mysql.configure">
  For compiling, simply use the 
  <option role="configure">--with-mysql[=DIR]</option>
  configuration option where the optional <literal>[DIR]</literal> points to 
  the MySQL installation directory.
 </para>
 <para> 
  Although this MySQL extension is compatible with MySQL 4.1.0 and greater, 
  it doesn't support the extra functionality that these versions provide. 
  For that, use the <link linkend="ref.mysqli">MySQLi</link> extension.
 </para>
 <para>
  If you would like to install the mysql extension along with the mysqli extension
  you have to use the same client library to avoid any conflicts.
 </para>

 <section xml:id="mysql.installation.linux">
  <title>Installation on Linux Systems</title>
  <section>
   <title>PHP 4</title>
   <para>
    The option <option role="configure">--with-mysql</option> is
    enabled by default. This default behavior may be disabled with the 
    <option role="configure">--without-mysql</option> configure option.  
    If MySQL is enabled without specifying the path to the
    MySQL install DIR, PHP will use the bundled MySQL client libraries.
   </para>
   <para>
    Users who run other applications that use MySQL (for example,
    <literal>auth-mysql</literal>) should not use the bundled library, but rather specify the
    path to MySQL's install directory, like so:
    <option role="configure">--with-mysql=/path/to/mysql</option>.
    This will force PHP to use the client libraries installed by MySQL, thus 
    avoiding any conflicts.
   </para>
  </section>
  <section>
   <title>PHP 5.0.x, 5.1.x, 5.2.x</title>
   <para>
    MySQL is not enabled by default, nor is the MySQL library
    bundled with PHP. Read this <link linkend="faq.databases.mysql.php5">
    FAQ</link> for details on why. Use the 
    <option role="configure">--with-mysql[=DIR]</option> configure option
    to include MySQL support.
    You can download <emphasis>headers and libraries</emphasis> from
    <link xlink:href="&url.mysql;">MySQL</link>.
   </para>
  </section>
  <section xml:id="mysql.installation.linux.mysqlnd">
    <title>PHP 5.3.0+</title>
    <para>
      In PHP 5.3.0 and above the MySQL-related database extensions use the 
      <link linkend="mysqlnd.overview">MySQL Native Driver</link> 
      by default. This means that the MySQL Client Library (<literal>libmysql</literal>) 
      is no longer required in order to support connection to a MySQL database. The extensions
      <literal>mysql</literal>, <literal>mysqli</literal>, and <literal>PHP_PDO_MYSQL</literal> are
      all enabled by default in PHP 5.3.0+, and all use the MySQL Native Driver by default. In each
      case no further installation steps are required in order to use these extensions, although
      you may want to set some preferences in <filename>php.ini</filename> depending on your 
      requirements.
    </para>
  </section>
 </section>

 <section xml:id="mysql.installation.windows">
  <title>Installation on Windows Systems</title>
  <section>
   <title>PHP 4</title>
   <para>
    The PHP MySQL extension is compiled into PHP.
   </para>
  </section>
  <section>
   <title>PHP 5.0.x, 5.1.x, 5.2.x</title>
   <para>
    MySQL is no longer enabled by default, so the 
    <filename>php_mysql.dll</filename> DLL must be enabled inside of 
    &php.ini;. Also, PHP needs access to the MySQL client library. A file
    named <filename>libmysql.dll</filename> is included in the Windows PHP 
    distribution and in order for PHP to talk to MySQL this file needs to be 
    available to the Windows systems <envar>PATH</envar>. See the FAQ
    titled "<link linkend="faq.installation.addtopath">How do I add my PHP 
    directory to the <varname>PATH</varname> on Windows</link>" for information on how to do
    this. Although copying <filename>libmysql.dll</filename> to the Windows
    system directory also works (because the system directory is by default in 
    the system's <envar>PATH</envar>), it's not recommended.
   </para>
   <para>
    As with enabling any PHP extension (such as 
    <filename>php_mysql.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 extension_dir value for PHP 5 is
    <literal>c:\php\ext</literal>
   </para>
   <note>
    <para>
     If when starting the web server an error similar to the following occurs:
     <literal>"Unable to load dynamic library './php_mysql.dll'"</literal>, 
     this is because <filename>php_mysql.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>
      Please refer to <link linkend="mysql.installation.linux.mysqlnd">these notes</link> on
      installing MySQL support on PHP 5.3.0 and above.
    </para>
  </section>
 </section>

 <section xml:id="mysql.installation.notes">
  <title>MySQL Installation Notes</title>
   <warning>
    <para>
     Crashes and startup problems of PHP may be encountered
     when loading this extension in conjunction with the recode extension.
     See the <link linkend="ref.recode">recode</link> extension for more
     information.
    </para>
   </warning>
   <note>
    <para>
     If you need charsets other than <emphasis>latin</emphasis> (default), you
     have to install external (not bundled) libmysql with compiled charset
     support. 
    </para>
   </note>
 </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
-->