Rewrote to clarify installation/configuration procedures, with

particular reference to using MySQL Native Driver with mysqli.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@275503 c90b9560-bf6c-de11-be94-00142212c4b1

reference/mysqli/configure.xml

@@ -1,56 +1,139 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
 <section xml:id="mysqli.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
- &reftitle.install;
+
+&reftitle.install;
+
  <para xml:id="mysqli.configure">
-  To install the <literal>mysqli</literal> extension for PHP, use the
-  <option role="configure">--with-mysqli=mysql_config_path/mysql_config</option>
-  configuration option where <literal>mysql_config_path</literal>
-  represents the location of the <literal>mysql_config</literal> program
-  that comes with MySQL versions greater than 4.1.
+  As of PHP 5.0, MySQL support is no longer enabled by default with the
+  standard PHP distributions. This means PHP needs to be explicitly
+  configured to take advantage of the MySQL extensions.
  </para>
 
  <para>
-  With versions of PHP 5.3 and newer, you can alternatively use
-  <option role="configure">--with-mysqli=mysqlnd</option>. 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
+  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>
+
+ <para>
+  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>
+
+ <note>
+  <para>
+   The <literal>mysql_config_path</literal> represents the location of
+   the <literal>mysql_config</literal> program that comes with MySQL
+   Server versions greater than 4.1.
+  </para>
+ </note>
+
+ <para>
+  With versions of PHP 5.3 and newer, you can alternatively use the new
+  MySQL Native Driver with <literal>mysqli</literal>. This gives a
+  number of benefits over using libmysql.
+ </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>
+  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>
-  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.
+  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 xml:id="mysqli.installation.windows">
 
   <title>Installation on Windows Systems</title>
 
   <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;. 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 PATH 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.
+   On Windows, PHP is most commonly installed using the binary
+   installer. 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>
+   As mentioned earlier, 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
+   [PHP_MYSQLI].
+  </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>
    On Windows, for PHP versions 5.3 and newer, the
    <literal>mysqli</literal> extension uses the MySQL Native Driver by
    default. This means you don't need to worry about configuring access
-   to <filename>libmysql.dll</filename>.
+   to <filename>libmysql.dll</filename>, you just need to make sure the
+   extension is enabled in the &php.ini; file.
   </para>
 
   <para>
@@ -59,8 +142,8 @@
    <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>
+   Instructions</link>. An example <literal>extension_dir</literal>
+   value for PHP 5 is <filename>c:\php\ext</filename>.
   </para>
 
   <note>