<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.23 $ -->
   <sect1 xml:id="install.windows.manual" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
    <title>Manual Installation Steps</title>
    
    <para>
     This install guide will help you manually install and configure PHP with
     a web server on Microsoft Windows.  To get started you'll need to download 
     the zip binary distribution from the downloads page at
     <link xlink:href="&url.php.downloads;">&url.php.downloads;</link>.
    </para>
    
    <para>
     Although there are many all-in-one installation kits, and we also 
     distribute a PHP installer for Microsoft Windows, we recommend you take 
     the time to setup PHP yourself as this will provide you with a better 
     understanding of the system, and enables you to install PHP extensions 
     easily when needed.
    </para>
    
    <note xml:id="install.windows.manual.upgrade">
     <title>Upgrading from a previous PHP version</title>
     <para>
      Previous editions of the manual suggest moving various ini and 
      <acronym>DLL</acronym> files into your SYSTEM (i.e. 
      <filename class="directory">C:\WINDOWS</filename>) folder and while this 
      simplifies the installation procedure it makes upgrading difficult.  We 
      advise you remove all of these files (like &php.ini; and PHP related
      DLLs from the Windows SYSTEM folder) before moving on with a new 
      PHP installation.  Be sure to backup these files as you might break the
      entire system.  The old &php.ini; might be useful in setting up the new
      PHP as well.  And as you'll soon learn, the preferred method for 
      installing PHP is to keep all PHP related files in one directory and
      have this directory available to your systems PATH.
     </para>
    </note>
    
    <note>
     <title>MDAC requirements</title>
     <para>
      If you use Microsoft <emphasis>Windows 98/NT4</emphasis> download the
      latest version of the Microsoft Data Access Components (MDAC) for your
      platform. MDAC is available at <link xlink:href="&url.mdac;">&url.mdac;</link>.
      This requirement exists because <link linkend="ref.uodbc">ODBC</link> is
      built into the distributed Windows binaries.
     </para>
    </note>
    
    <para>
     The following steps should be completed on all installations before any
     server specific instructions are performed:
    </para>
    <para>
     Extract the distribution file into a directory of your choice. If you
     are installing PHP 4, extract to <filename
      class="directory">C:\</filename>, as the zip file expands to a
     foldername like <filename>php-4.3.7-Win32</filename>. If you are
     installing PHP 5, extract to <filename
      class="directory">C:\php</filename> as the zip file doesn't expand as in
     PHP 4. You may choose a different location but do not have spaces in the
     path (like <filename class="directory">C:\Program Files\PHP</filename>)
     as some web servers will crash if you do.
    </para>
    <para>
     The directory structure extracted from the zip is different for PHP 
     versions 4 and 5 and look like as follows:
    </para>
    <example>
     <title>PHP 4 package structure</title>
     <programlisting>
<![CDATA[

c:\php
   |
   +--cli
   |  |
   |  |-php.exe           -- CLI executable - ONLY for command line scripting
   |
   +--dlls                -- support DLLs required by some extensions
   |  |
   |  |-expat.dll
   |  |
   |  |-fdftk.dll
   |  |
   |  |-...
   |
   +--extensions          -- extension DLLs for PHP
   |  |
   |  |-php_bz2.dll
   |  |
   |  |-php_cpdf.dll
   |  |
   |  |-...
   |
   +--mibs                -- support files for SNMP
   |
   +--openssl             -- support files for Openssl
   |
   +--pdf-related         -- support files for PDF
   |
   +--sapi                -- SAPI (server module support) DLLs
   |  |
   |  |-php4apache.dll
   |  |
   |  |-php4apache2.dll
   |  |
   |  |-...
   |
   +--PEAR                -- initial copy of PEAR
   |
   |
   |-go-pear.bat          -- PEAR setup script
   |
   |-...
   |
   |-php.exe              -- CGI executable
   |
   |-...
   |
   |-php.ini-dist         -- default php.ini settings
   |
   |-php.ini-recommended  -- recommended php.ini settings
   | 
   |-php4ts.dll           -- core PHP DLL
   | 
   |-...

]]>
     </programlisting>
    </example> 
    <para>
    Or:
    </para>
    <example>
     <title>PHP 5 package structure</title>
     <programlisting>
<![CDATA[

c:\php
   |
   +--dev
   |  |
   |  |-php5ts.lib
   |
   +--ext                 -- extension DLLs for PHP
   |  |
   |  |-php_bz2.dll
   |  |
   |  |-php_cpdf.dll
   |  |
   |  |-...
   |
   +--extras
   |  |
   |  +--mibs             -- support files for SNMP
   |  |
   |  +--openssl          -- support files for Openssl
   |  |
   |  +--pdf-related      -- support files for PDF
   |  |
   |  |-mime.magic
   |
   +--pear                -- initial copy of PEAR
   |
   |
   |-go-pear.bat          -- PEAR setup script
   |
   |-fdftk.dll
   |
   |-...
   |
   |-php-cgi.exe          -- CGI executable
   |
   |-php-win.exe          -- executes scripts without an opened command prompt
   |
   |-php.exe              -- CLI executable - ONLY for command line scripting
   |
   |-...
   |
   |-php.ini-dist         -- default php.ini settings
   |
   |-php.ini-recommended  -- recommended php.ini settings
   | 
   |-php5activescript.dll
   |
   |-php5apache.dll
   |
   |-php5apache2.dll
   |
   |-...
   |
   |-php5ts.dll           -- core PHP DLL
   | 
   |-...

]]>
     </programlisting>
    </example> 
    <para>
     Notice the differences and similarities.  Both PHP 4 and PHP 5 have a 
     <acronym>CGI</acronym> executable, a <acronym>CLI</acronym> executable,
     and server modules, but they are located in different folders and/or have
     different names.  While PHP 4 packages have the server modules in the 
     <filename class="directory">sapi</filename> folder, PHP 5 
     distributions have no such directory and instead they're in the PHP
     folder root. The supporting DLLs for the PHP 5 extensions are also not
     in a seperate directory.
    </para>
    <note>
     <para>
      In PHP 4, you should move all files located in the <filename
       class="directory">dll</filename> and <filename
       class="directory">sapi</filename> folders to the main folder (e.g.
      <filename class="directory">C:\php</filename>).
     </para>
    </note>
    <para>
     Here is a list of server modules shipped with PHP 4 and PHP 5:
     <itemizedlist>
      <listitem><para>
       <filename>sapi/php4activescript.dll (php5activescript.dll)</filename>
       - <link linkend="install.windows.activescript">ActiveScript
        engine</link>, allowing you to embed PHP in your Windows
       applications.
      </para></listitem>
      <listitem><para>
       <filename>sapi/php4apache.dll (php5apache.dll)</filename> - Apache 1.3.x module.
      </para></listitem>
      <listitem><para>
       <filename>sapi/php4apache2.dll (php5apache2.dll)</filename> - Apache 2.0.x module.
      </para></listitem>
      <listitem><para>
       <filename>sapi/php5apache2_2.dll</filename> - Apache 2.2.x module.
      </para></listitem>
      <listitem><para>
       <filename>sapi/php4isapi.dll (php5isapi.dll)</filename> - ISAPI Module
       for ISAPI compliant web servers like IIS 4.0/PWS 4.0 or newer.
      </para></listitem>
      <listitem><para>
       <filename>sapi/php4nsapi.dll (php5nsapi.dll)</filename> - Sun/iPlanet/Netscape
       server module.
      </para></listitem>
      <listitem><para>
       <filename>sapi/php4pi3web.dll (no equivalent in PHP 5)</filename> - Pi3Web server module.
      </para></listitem>
       <!-- TODO: servlets? -->
     </itemizedlist>
    </para>
    <para>
     Server modules provide significantly better performance and additional 
     functionality compared to the CGI binary. The CLI version is designed to
     let you use PHP for command line scripting. More information about CLI is
     available in the chapter about <link linkend="features.commandline">using
     PHP from the command line</link>.
    </para>
    <warning>
     <simpara>
      The SAPI modules have been significantly improved as of the 4.1 release,
      however, in older systems you may encounter server errors or other
      server modules failing, such as ASP.
     </simpara>
    </warning>
    <para>
     The CGI and CLI binaries, and the web server modules all require the
     <filename>php4ts.dll</filename> (<filename>php5ts.dll</filename>) file to
     be available to them. You have to make sure that this file can be found
     by your PHP installation. The search order for this DLL is as follows:
     <itemizedlist>
      <listitem>
       <para>
        The same directory from where <filename>php.exe</filename> is called,
        or in case you use a SAPI module, the web server's directory (e.g.
        <filename>C:\Program Files\Apache Group\Apache2\bin</filename>).
       </para>
      </listitem>
      <listitem>
       <para>
        Any directory in your Windows <varname>PATH</varname> environment
        variable.
       </para>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     To make <filename>php4ts.dll</filename> / <filename>php5ts.dll</filename>
     available you have three options: copy the file to the Windows system
     directory, copy the file to the web server's directory, or add your PHP
     directory, <filename class="directory">C:\php</filename> to the
     <varname>PATH</varname>. For better maintenance, we advise you to follow
     the last option, add <filename class="directory">C:\php</filename> to the
     <varname>PATH</varname>, because it will be simpler to upgrade PHP in the
     future. Read more about how to add your PHP directory to
     <varname>PATH</varname> in the <link
      linkend="faq.installation.addtopath">corresponding FAQ entry</link> (and
      then don't forget to restart the computer - logoff isn't enough).
    </para>
    <para>
     The next step is to set up a valid configuration file for PHP, &php.ini;.
     There are two ini files distributed in the zip file,
     <filename>php.ini-dist</filename> and
     <filename>php.ini-recommended</filename>. We advise you to use
     <filename>php.ini-recommended</filename>, because we optimized the
     default settings in this file for performance, and security. Read this
     well documented file carefully because it has changes from
     <filename>php.ini-dist</filename> that will drastically affect your 
     setup.  Some examples are <link linkend="ini.display-errors">
     display_errors</link> being <literal>off</literal> and 
     <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> being
     <literal>off</literal>.  In addition to reading these, study the <link
     linkend="configuration.file">ini settings</link> and set every element
     manually yourself. If you would like to achieve the best security, then
     this is the way for you, although PHP works fine with these default ini
     files. Copy your chosen ini-file to a directory that PHP is able to find
     and rename it to &php.ini;. PHP searches for &php.ini; in the locations
     described in <xref linkend="configuration.file"/> section.
    </para>
    <para>
     If you are running Apache 2, the simpler option is to use the PHPIniDir
     directive (read the <link linkend="install.windows.apache2">installation
     on Apache 2</link> page), otherwise your best option is to set the
     <varname>PHPRC</varname> environment variable. This process is explained
     in the following <link linkend="faq.installation.phprc">FAQ entry</link>.
    </para>
    <note>
     <simpara>
      If you're using NTFS on Windows NT, 2000, XP or 2003, make sure that the
      user running the web server has read permissions to your &php.ini; (e.g.
      make it readable by Everyone).
     </simpara>
    </note>
    <para>
     The following steps are optional:
     <itemizedlist>
      <listitem>
       <para>
        Edit your new &php.ini; file.       
        If you plan to use <link linkend="install.windows.omnihttpd">OmniHTTPd</link>,
        do not follow the next step. Set the
        <link linkend="ini.doc-root">doc_root</link> to point to your 
        web servers document_root. For example:
        <informalexample>
          <programlisting role="ini">
<![CDATA[
doc_root = c:\inetpub\wwwroot // for IIS/PWS

doc_root = c:\apache\htdocs // for Apache
]]>
         </programlisting>
        </informalexample>
       </para>
      </listitem>
      <listitem>
       <simpara>
        Choose the extensions you would like to load when PHP starts. See
        the section about
        <link linkend="install.windows.extensions">Windows extensions</link>,
        about how to set up one, and what is already built in. Note that on
        a new installation it is advisable to first get PHP working and tested
        without any extensions before enabling them in &php.ini;.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        On PWS and IIS, you can set the
        <link linkend="ini.browscap">browscap</link> configuration setting
        to point to:
        <filename>c:\windows\system\inetsrv\browscap.ini</filename> on
        Windows 9x/Me,
        <filename>c:\winnt\system32\inetsrv\browscap.ini</filename> on
        NT/2000, and
        <filename>c:\windows\system32\inetsrv\browscap.ini</filename>
        on XP.  For an up-to-date <filename>browscap.ini</filename>, read the
        following <link linkend="faq.obtaining.browscap">FAQ</link>.
       </simpara>
      </listitem>
     </itemizedlist>
    </para> 
    <para>
     PHP is now setup on your system.  The next step is to choose a web
     server, and enable it to run PHP.  Choose a web server from the table of 
     contents.
    </para>
   </sect1>

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