<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.21 $ -->
<sect1 xml:id="install.windows.iis" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Microsoft IIS / PWS</title>
 <para>
  This section contains notes and hints specific to IIS (Microsoft
  Internet Information Server).
 </para>

 &warn.install.cgi;

 <sect2 xml:id="install.windows.iis.general">
  <title>General considerations for all installations of PHP with IIS or PWS</title>
  <para>
   <itemizedlist>
    <listitem>
     <simpara>
      First, read the <link linkend="install.windows.manual">Manual 
      Installation Instructions</link>. Do not skip this step as it
      provides crucial information for installing PHP on Windows.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      CGI users must set the <link linkend="ini.cgi.force-redirect">
      cgi.force_redirect</link> PHP directive to <literal>0</literal>
      inside &php.ini;. Read the 
      <link linkend="faq.installation.forceredirect">faq on 
      cgi.force_redirect</link> for important details. Also, CGI users 
      may want to set the <link linkend="ini.cgi.redirect-status-env">
      cgi.redirect_status_env</link> directive. When using directives, be 
      sure these directives aren't commented out inside &php.ini;.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The PHP 4 CGI is named <filename>php.exe</filename> while in PHP 5 it's 
      <filename>php-cgi.exe</filename>. In PHP 5, <filename>php.exe</filename> 
      is the CLI, and not the CGI.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Modify the Windows <literal>PATH</literal> environment variable to 
      include the PHP directory. This way the PHP DLL files and PHP executables
      can all remain in the PHP directory without cluttering
      up the Windows system directory. For more details, see the FAQ on 
      <link linkend="faq.installation.addtopath">Setting the PATH</link>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The IIS user (usually IUSR_MACHINENAME) needs permission to
      read various files and directories, such as &php.ini;, docroot, and the
      session tmp directory.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Be sure the <link linkend="ini.extension-dir">extension_dir</link> 
      and <link linkend="ini.doc-root">doc_root</link> PHP directives are
      appropriately set in &php.ini;. These directives depend on the system 
      that PHP is being installed on. In PHP 4, the extension_dir is 
      <filename>extensions</filename> while with PHP 5 it's 
      <filename>ext</filename>. So, an example PHP 5 extensions_dir value is 
      <filename>"c:\php\ext"</filename> and an example IIS doc_root value is 
      <filename>"c:\Inetpub\wwwroot"</filename>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      PHP extension DLL files, such as <filename>php_mysql.dll</filename> and  
      <filename>php_curl.dll</filename>, are found in the zip package of the
      PHP download (not the PHP installer). In PHP 5, many extensions are part
      of PECL and can be downloaded in the "Collection of PECL modules"
      package. Files such as <filename>php_zip.dll</filename> and
      <filename>php_ssh2.dll</filename>. 
      <link xlink:href="&url.php.downloads;">Download PHP files here</link>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      When defining the executable, the 'check that file exists' box may also 
      be checked. For a small performance penalty, the IIS (or PWS) will check 
      that the script file exists and sort out authentication before firing up 
      PHP. This means that the web server will provide sensible 404 style 
      error messages instead of CGI errors complaining that PHP did not output 
      any data.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The PHP executable is distributed as a 32bit application. If you are running
      a 64bit version of Windows you will either need to rebuild the binary yourself,
      or make sure IIS is configured to also run 32bit extensions. You can usually 
      turn this on by using the IIS Administration script as follows:
      Cscript.exe adsutil.vbs SET W3SVC/AppPools/Enable32bitAppOnWin64 1
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
 </sect2>

 <sect2 xml:id="install.windows.iis.iis4">
  <title>Windows NT/200x/XP and IIS 4 or newer</title>

  <simpara>
   PHP may be installed as a CGI binary, or with the ISAPI module.
   In either case, you need to start the Microsoft Management
   Console (may appear as 'Internet Services Manager', either
   in your Windows NT 4.0 Option Pack branch or the Control
   Panel=&gt;Administrative Tools under Windows 2000/XP). Then
   right click on your Web server node (this will most probably
   appear as 'Default Web Server'), and select 'Properties'.
  </simpara>

  <para>
   If you want to use the CGI binary, do the following:
   <itemizedlist>
    <listitem>
     <simpara>
      Under 'Home Directory', 'Virtual Directory', or 'Directory', do the 
      following:
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Change the Execute Permissions to 'Scripts only'
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Click on the 'Configuration' button, and choose the Application Mappings 
      tab. Click Add and set the Executable path to the appropriate CGI file.
      An example PHP 5 value is: <filename>C:\php\php-cgi.exe</filename>
      Supply <literal>.php</literal> as the extension. Leave 'Method 
      exclusions' blank, and check the 'Script engine' checkbox. Now, click 
      OK a few times.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Set up the appropriate security. (This is done in Internet
      Service Manager), and if your NT Server uses NTFS file system,
      add execute rights for I_USR_ to the directory that contains
      <filename>php.exe</filename> / <filename>php-cgi.exe</filename>.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   To use the ISAPI module, do the following:
   <itemizedlist>
    <listitem>
     <simpara>
      If you don't want to perform HTTP Authentication using PHP,
      you can (and should) skip this step. Under ISAPI Filters,
      add a new ISAPI filter. Use PHP as the filter name, and
      supply a path to the <filename>php4isapi.dll</filename> /
      <filename>php5isapi.dll</filename>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Under 'Home Directory', 'Virtual Directory', or 'Directory', do the 
      following:
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Change the Execute Permissions to 'Scripts only'
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Click on the 'Configuration' button, and choose the Application Mappings 
      tab. Click Add and set the Executable path to the appropriate ISAPI DLL.
      An example PHP 5 value is: <filename>C:\php\php5isapi.dll</filename>
      Supply <literal>.php</literal> as the extension. Leave 'Method 
      exclusions' blank, and check the 'Script engine' checkbox. Now, click 
      OK a few times.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Stop IIS completely (NET STOP iisadmin)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Start IIS again (NET START w3svc)
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   With IIS 6 (2003 Server), open up the IIS Manager, go to Web Service 
   Extensions, choose "Add a new Web service extension", enter in a name such 
   as PHP, choose the Add button and for the value browse to either the ISAPI 
   file (<filename>php4isapi.dll</filename> or 
   <filename>php5isapi.dll</filename>) or CGI (<filename>php.exe</filename> or 
   <filename>php-cgi.exe</filename>) then check "Set extension status to 
   Allowed" and click OK.
  </para>
  <para>
   In order to use <filename>index.php</filename> as a default content page, 
   do the following: From within the Documents tab, choose Add. Type in
   <filename>index.php</filename> and click OK. Adjust the order by choosing
   Move Up or Move Down. This is similar to setting DirectoryIndex with
   Apache.
  </para>
  <para>
   The steps above must be repeated for each extension that is to be 
   associated with PHP scripts. <literal>.php</literal> is the most common 
   although <literal>.php3</literal> may be required for legacy applications.
  </para>
  <para>
   If you experience 100% CPU usage after some time, turn off the IIS
   setting <literal>Cache ISAPI Application</literal>.
  </para>
 </sect2>

 <sect2 xml:id="install.windows.iis.pws4">
  <title>Windows and PWS 4</title>
  <simpara>
   PWS 4 does not support ISAPI, only PHP CGI should be used.
  </simpara>
  <para>
   <itemizedlist>
    <listitem>
     <simpara>
      Edit the enclosed <filename>pws-php4cgi.reg</filename> /
      <filename>pws-php5cgi.reg</filename> file (look into the SAPI folder
      for PHP 4, or in the main folder for PHP 5) to reflect the location of
      your <filename>php.exe</filename> / <filename>php-cgi.exe</filename>.
      Backslashes should be escaped, for example:
      <literal>[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script
       Map] ".php"="C:\\php\\php.exe"</literal> (change to
      <literal>C:\\php\\php-cgi.exe</literal> if you are using PHP 5)
      Now merge this registery file into your system; you may do
      this by double-clicking it.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      In the PWS Manager, right click on a given directory you want
      to add PHP support to, and select Properties. Check the 'Execute'
      checkbox, and confirm.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
 </sect2>

 <sect2 xml:id="install.windows.iis.iis3">
  <title>Windows and PWS/IIS 3</title>
  <simpara>
   The recommended method for configuring these servers is to use
   the REG file included with the distribution
   (<filename>pws-php4cgi.reg</filename> in the SAPI folder for PHP 4, or
   <filename>pws-php5cgi.reg</filename> in the main folder for PHP 5).
   You may want to edit this file and make sure
   the extensions and PHP install directories match your
   configuration. Or you can follow the steps below to do it
   manually.
  </simpara>
  <warning>
   <para>
    These steps involve working directly with the Windows
    registry. One error here can leave your system in an unstable
    state. We highly recommend that you back up your registry
    first. The PHP Development team will not be held responsible if
    you damage your registry.
   </para>
  </warning>

  <para>
   <itemizedlist>
    <listitem>
     <simpara>
      Run Regedit.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Navigate to: <literal>HKEY_LOCAL_MACHINE /System
       /CurrentControlSet /Services /W3Svc /Parameters
       /ScriptMap</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      On the edit menu select: <literal>New->String Value</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Type in the extension you wish to use for your php
      scripts. For example <literal>.php</literal>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Double click on the new string value and enter the path to
      <filename>php.exe</filename> in the value data field. ex:
      <filename>C:\php\php.exe "%s" %s</filename> for PHP 4, or
      <filename>C:\php\php-cgi.exe "%s" %s</filename> for PHP 5.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Repeat these steps for each extension you wish to associate
      with PHP scripts.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   The following steps do not affect the web server installation
   and only apply if you want your PHP scripts to be executed when
   they are run from the command line (ex. run
   <filename>C:\myscripts\test.php</filename>) or by double clicking
   on them in a directory viewer window. You may wish to skip these
   steps as you might prefer the PHP files to load into a text
   editor when you double click on them.
  </para>
  <para>
   <itemizedlist>
    <listitem>
     <simpara>
      Navigate to: <literal>HKEY_CLASSES_ROOT</literal>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      On the edit menu select: <literal>New->Key</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Name the key to the extension you setup in the previous
      section. ex: <literal>.php</literal>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Highlight the new key and in the right side pane, double click
      the "default value" and enter <literal>phpfile</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Repeat the last step for each extension you set up in the
      previous section.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Now create another <literal>New->Key</literal> under
      <literal>HKEY_CLASSES_ROOT</literal> and name it
      <literal>phpfile</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Highlight the new key <literal>phpfile</literal> and in the
      right side pane, double click the "default value" and enter
      <literal>PHP Script</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Right click on the <literal>phpfile</literal> key and select
      <literal>New->Key</literal>, name it <literal>Shell</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Right click on the <literal>Shell</literal> key and select
      <literal>New->Key</literal>, name it <literal>open</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Right click on the <literal>open</literal> key and select
      <literal>New->Key</literal>, name it
      <literal>command</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Highlight the new key <literal>command</literal> and in the
      right side pane, double click the "default value" and enter
      the path to <filename>php.exe</filename>. ex:
      <literal>c:\php\php.exe -q %1</literal>. (don't forget the
      <literal>%1</literal>).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Exit Regedit.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      If using PWS on Windows, reboot to reload the registry.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   PWS and IIS 3 users now have a fully operational system. IIS 3
   users can use a nifty <link xlink:href="&url.iiscfg;">tool</link>
   from Steven Genusa to configure their script maps.
  </simpara>
 </sect2>
</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
-->