revise install instructions

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

reference/pdo/reference.xml

@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.30 $ -->
+<!-- $Revision: 1.31 $ -->
 <!-- Purpose: database.abstract -->
 <!-- Membership: pecl, bundled -->
 <!-- State:experimental -->
@@ -21,59 +21,101 @@
      itself; you must use a <link linkend="pdo.drivers">database-specific
      PDO driver</link> to access a database server.
     </para>
+    <para>
+     PDO ships with PHP 5.1, and is available as a PECL extension for PHP 5.0;
+     PDO requires the new OO features in the core of PHP 5, and so will not
+     run with earlier versions of PHP.
+    </para>
    </section>
    <section id="pdo.installation">
    &reftitle.install;
-   <!-- Uncomment this section when PDO actually stabilizes and PEAR method
-   works -->
-   <!--
-    <para>
-     PDO is currently available as a PECL extension from
-     <ulink url='&url.pecl.package;pdo'>&url.pecl.package;pdo</ulink>.
-     Ensure you have installed the CLI version of PHP and that the
-     <command>pear</command> and <command>phpize</command> scripts are
-     available in your current path.
-    </para>
-    <para>
-     Run the following command to download, build, and install the
-     latest stable version of PDO:
-     <screen>
+    <procedure id='pdo.install.unix51up'>
+     <title>PHP 5.1 and up on Unix systems</title>
+     <para>
+      If you're running a PHP 5.1 release, PDO is included in the distribution;
+      it will be automatically enabled when you run configure.  It is
+      recommended that you build PDO as a shared extension, as this will allow
+      you to take advantage of updates that are made available via PECL.  The
+      recommended configure line for building PHP with PDO support should
+      enable zlib support (for the pear installer) as well.  You may also need
+      to enable the PDO driver for your database of choice; consult the
+      documentation for  <link linkend="pdo.drivers">database-specific
+      PDO drivers</link> to find out more about that.
+      <screen>
 <![CDATA[
-pear install pdo
+ ./configure --with-zlib --enable-pdo=shared
 ]]>
-     </screen>
-    </para>
-    <para>
-     The <command>pear</command> command automatically installs the
-     PDO module into your PHP extensions directory. To enable the
-     PDO extension on Linux or Unix operating systems, you must add
-     the following line to &php.ini;:
-     <screen>
+      </screen>
+     </para>
+     <para>
+      After installing PDO as a shared module, you must edit your php.ini file
+      so that the PDO extension will be loaded automatically when PHP runs.
+      You will also need to enable any database specific drivers there too;
+      make sure that they are listed after the pdo.so line, as PDO must be
+      initialized before the database specific extensions can be loaded.
+      If you built the extensions statically, you can skip this step.
+      <screen>
 <![CDATA[
 extension=pdo.so
 ]]>
-     </screen>
-    </para>
-     -->
-    <procedure id='installwindows'>
-     <title>Windows</title>
-     <para>
-      Follow the same steps to install and enable the PDO drivers of your
-      choice.
+      </screen>
      </para>
+     <para>
+      Having PDO as a shared module will allow you to run <command>pear
+      upgrade pdo</command> as new versions of PDO are published, without
+      forcing you to rebuild the whole of PHP.  Note that if you do this, you
+      also need to upgrade your database specific PDO drivers at the same
+      time.
+     </para>
+    </procedure>
+    <procedure id='pdo.install.pecl'>
+     <title>PHP 5.0 and up on Unix systems</title>
+     <para>
+      PDO is available as a PECL extension from
+      <ulink url='&url.pecl.package;pdo'>&url.pecl.package;pdo</ulink>.
+      Installation can be performed via the <command>pear</command> tool; this
+      is enabled by default when you configure PHP.  You should ensure that
+      PHP was configured --with-zlib in order for
+      <command>pear</command> to be able to handle the compressed package
+      files.
+     </para>
+     <para>
+      Run the following command to download, build, and install the
+      latest stable version of PDO:
+      <screen>
+<![CDATA[
+pear install pdo
+]]>
+      </screen>
+     </para>
+     <para>
+      If PDO is still in beta (and at the time of writing, it is), you will
+      need to tell the pear tool that it's ok to fetch the beta package.
+      Instead of running the command above, run the following:
+      <screen>
+<![CDATA[
+pear install pdo-beta
+]]>
+      </screen>
+     </para>
+     <para>
+      The <command>pear</command> command automatically installs the
+      PDO module into your PHP extensions directory. To enable the
+      PDO extension on Linux or Unix operating systems, you must add
+      the following line to &php.ini;:
+      <screen>
+<![CDATA[
+extension=pdo.so
+]]>
+      </screen>
+     </para>
+    </procedure>
+    <procedure id='pdo.install.win32php51'>
+     <title>Windows users running PHP 5.1 and up</title>
      <step>
       <para>
-       Windows users can download the extension DLL <filename>php_pdo.dll</filename>
-       as part of the PECL collection binaries from
-       <ulink url='&url.php.downloads;'>&url.php.downloads;</ulink> or a more 
-       recent version from a <ulink url="&url.pecl.get.win.php5.0;">PHP 5 PECL 
-       Snapshot</ulink>.
-      </para>
-     </step>
-     <step>
-      <para>
-       To enable the PDO extension on Windows operating systems, you must
-       add the following line to &php.ini;:
+       PDO and all the major drivers ship with PHP as shared extensions, and
+       simply need to be activated by editing the &php.ini; file:
        <screen>
 <![CDATA[
 extension=php_pdo.dll
@@ -106,62 +148,6 @@ extension=php_pdo_sqlite.dll
       </para>
      </step>
     </procedure>
-    <procedure id='installunix'>
-     <title>Linux and UNIX</title>
-     <para>
-      Due to a bug in the <command>pear</command> installer you should install
-      the PDO package manually using the following steps:
-     </para>
-     <para>
-      Follow the same steps to install and enable the PDO drivers of your
-      choice. E.g. for MySQL driver, replace PDO with PDO_MYSQL in the
-      following instructions.
-     </para>
-     <step>
-      <para>Download the PDO package to your local machine:
-       <screen>
-<![CDATA[
-bash$  wget http://pecl.php.net/get/PDO
-]]>
-       </screen>
-      </para>
-     </step>
-     <step>
-      <para>
-       Determine your PHP <filename>bin</filename> directory. If your
-       PHP 5 CLI binary lives at <filename>/usr/local/php5/bin/php</filename>
-       then the bin dir is <filename>/usr/local/php5/bin</filename>.
-      </para>
-     </step>
-     <step>
-      <para>
-       Set your path so that your PHP <filename>bin</filename> directory
-       is at the front:
-       <screen>
-<![CDATA[
-    export PATH="/usr/local/php5/bin:$PATH"
-]]>
-       </screen>
-      </para>
-     </step>
-     <step>
-      <para>
-       Manually build and install the PDO extension:
-       <screen>
-<![CDATA[
-bash$ tar xzf PDO-0.9.tgz
-bash$ cd PDO-0.9
-bash$ phpize
-bash$ ./configure
-bash$ make
-bash$ sudo -s
-bash# make install
-bash# echo extension=pdo.so >> /usr/local/php5/lib/php.ini
-]]>
-       </screen>
-      </para>
-     </step>
-    </procedure>
    </section>
 
    &reference.pdo.ini;