path: root/win32/install.txt

PHP/Windows Installation Notes
==============================

Installation on Windows 9x/Me/NT/2000/XP systems
=============================================

There are two main ways to install PHP for Windows: either
manually or by using the InstallShield installer.


Windows InstallShield
=====================

 The Windows PHP installer is available from the downloads page at
 www.php.net. This installs the CGI version of PHP and, for IIS, PWS,
 and Xitami, configures the web server as well.
 Note that this version does *NOT* install any extensions or server
 api versions of PHP.

 Install your selected HTTP server on your system and make sure
 that it works.

 Run the executable installer and follow the instructions provided by
 the installation wizard. Two types of installation are supported -
 standard, which provides sensible defaults for all the settings it
 can, and advanced, which asks questions as it goes along.

 The installation wizard gathers enough information to set up the
 php.ini file and configure the web server to use PHP.
 For IIS and also PWS on NT Workstation, a list of all the
 nodes on the server with script map settings is displayed, and you
 can choose those nodes to which you wish to add the PHP script
 mappings.

 Once the installation has completed the installer will inform you
 if you need to restart your system, restart the server, or just
 start using PHP.

Windows Manual installation from zip binary distribution
========================================================

 This install guide will help you manually install and configure
 PHP on your Windows 9x/Me/NT/2000/XP webservers. This guide was compiled by
 Bob Silva. The original version can be found at
 http://www.umesd.k12.or.us/php/win32install.html

 This guide provides manual installation support for:
  Personal Web Server 3 and 4 or newer
  Internet Information Server 3 and 4 or newer
  Apache 1.3.x
  OmniHTTPd 2.0b1 and up
  Oreilly Website Pro
  Xitami
  Netscape Enterprise Server, iPlanet

 PHP 4 for Windows comes in two flavours - a CGI executable (php-cgi.exe),
 and several SAPI modules (for exapmle php4isapi.dll). The latter form
 is new to PHP 4, and provides significantly improved performance and
 some new functionality. However, please note that the SAPI modules
 are *NOT* yet considered to be production quality.
 In particular, with the ISAPI module, you are likely to encounter serious
 reliability problems especially on platforms older than W2K - you may
 witness a lot of server 500 errors and suffer from other server modules
 such as ASP also failing. You have been warned!

 The reason for this is that the PHP SAPI modules are using the
 thread-safe version of the PHP code, which is new to PHP 4, and has
 not yet been tested and pounded enough to be considered completely
 stable, and there are actually a few known bugs. On the other hand,
 some people have reported very good results with the SAPI modules,
 and there a few reports of problems with the Apache module version.
 In short - your mileage may vary;  If you need
 absolute stability, trade the performance of the SAPI modules
 with the stability of the CGI executable.

 If you choose one of the SAPI modules and use Windows 95, be sure
 to download the DCOM update from
 http://download.microsoft.com/msdownload/dcom/95/x86/en/dcom95.exe"
 For the ISAPI module, an ISAPI 4.0 compliant Web server
 is required (tested on IIS 4.0, PWS 4.0 and IIS 5.0). IIS 3.0 is
 *NOT* supported; You should download and install the Windows NT 4.0
 Option Pack with IIS 4.0 if you want native PHP support.

 The following steps should be performed on all installations
 before the server specific instructions.

  Extract the distribution file to a directory of your choice.
  C:\PHP\ is a good start.

  You need to ensure that the dlls which php uses can be found. The precise
  dlls involved depend on which web server you use and whether you want to
  run php as a cgi or as a server module. php4ts.dll is always used. If you are
  using a server module (e.g. isapi or apache) then you will need the relevent
  dll from the sapi folder. If you are using any php extension dlls then you
  will need those as well. To make sure that the dlls can be found, you can
  either copy them to the system directory (e.g. winnt/system32 or 
  windows/system) or you can make sure that they live in the same directory
  as the main php executable or dll your web server will use (e.g. php-cgi.exe,
  php4apache.dll).

  Copy the file, php.ini-dist to your %WINDOWS% directory on
  Windows 95/98 or to your %SYSTEMROOT% directory under Windows NT,
  Windows 2000 or Windows XP and rename it to php.ini. Your %WINDOWS% or
  %SYSTEMROOT% directory is typically:
   c:\windows for Windows 95/98
   c:\winnt or c:\winnt40 for NT/2000/XP servers

  Edit your php.ini file:

   You will need to change the 'extension_dir' setting to
   point to your php-install-dir, or where you have placed
   your 'php_*.dll' files. ex: c:\php

   If you are using OmniHTTPd, do not follow the next step.
   Set the 'doc_root' to point to your webservers
   document_root. ex: c:\apache\htdocs or c:\webroot

   Choose which extensions you would like to load when PHP
   starts, noting that several extensions are already built
   into the Windows release, see the section about
   Windows extensions for details of the built-in extensions.
   You can uncomment the: 'extension=php_*.dll' lines
   in php.ini to load these extensions.

   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.

   On PWS and IIS, you can set the browscap.ini
   to point to: 'c:\windows\system\inetsrv\browscap.ini' on
   Windows 9x/Me and 'c:\winnt\system32\inetsrv\browscap.ini'
   on NT/2000/XP Server. 

   More information on the capabilities of browscap can be found here:

   http://www.php.net/manual/en/function.get-browser.php

   Note that the mibs directory supplied with the Windows distribution
   contains support files for SNMP. This directory should be moved to
   DRIVE:\usr\mibs (DRIVE being the drive where PHP is installed.)


Installation of Windows extensions
==================================

 After installing PHP and a webserver on Windows, you will
 probably want to install some extensions for added functionality.
 The following table describes some of the extensions available. As
 described in the manual installation steps, you can choose which
 extensions you would like to load when PHP starts by uncommenting the:
 extension=php_*.dll' lines in php.ini.


 ATTENTION! ATTENTION! ATTENTION!
   Some extra DLLs are required for some PHP extensions. Please copy the
   bundled dlls from the 'dlls/' directory in distribution package to your
   windows/system (Win9.x) or winnt/system32 (WinNT, Win2000, XP) directory.
   If you already have these DLLs installed on your system,
   overwrite them only if something is not working correctly.
   Before overwriting them, it is a good idea to backup them or move them to
   another folder - just in case something goes wrong.

   Download the latest version of the Microsoft Data Access Components (MDAC)
   for your platform, especially Microsoft Windows 9x/NT4 users.
   MDAC is available at http://www.microsoft.com/data/ .

   Also note that some extensions need 3rd party libraries, 
   e.g. php_oci8.dll needs the Oracle 8 client libraries to be installed
   on your system. These are not bundled with PHP distribution.
 ATTENTION! ATTENTION! ATTENTION!


 The DLLs for PHP extensions are prefixed with 'php_'.  This
 prevents confusion between PHP extensions and their supporting
 libraries.

 Note:
 In PHP 4.0.5 MySQL, ODBC, FTP, Calendar, BCMath, COM, PCRE,
 Session, WDDX and XML support is built-in. You don't need to
 load any additional extensions in order to use these functions.

 Examples of PHP Extensions

  php_dbase.dll     dBase functions
  php_filepro.dll   Read-only access to Filepro databases
  php_gd.dll        GD library functions for GIF manipulation
  php_hyperwave.dll HyperWave functions
  php_imap.dll      IMAP functions
  php_ldap.dll      LDAP functions
  php_mssql.dll     MSSQL client (requires MSSQL DB-Libraries)
  php_snmp.dll      SNMP get and walk functions (NT only!)
  php_zlib.dll      ZLib compression functions

 For more information see the section about Windows extensions at
 http://www.php.net/manual/en/install-windows.php#install.windows.extensions


Web server configuration
========================

 Installing PHP on Windows with Apache 1.3.x

  There are two ways to set up PHP to work with Apache 1.3.x
  on Windows. One is to use the CGI binary (php-cgi.exe),
  the other is to use the Apache module dll. In either case
  you need to stop the Apache server, and edit your
  srm.conf or httpd.conf to configure Apache to work with PHP.

  Although there can be a few variations of configuring PHP
  under Apache, these are simple enough to be used by the
  newcomer. Please consult the Apache Docs for further
  configuration directives.

  Now that version 4.1 introduces a safer sapi module, we recommend
  that you configure PHP as a module in Apache.

  To do this, you should move php4ts.dll to the windows/system (for Windows 9x/Me)
  or winnt/system32 (for Windows NT/2000/XP) directory, overwriting any
  older file. Then you should add the following three lines to your Apache
  conf file: (swap c:/php/ for your PHP install path)

   LoadModule php4_module c:/php/sapi/php4apache.dll
   AddModule mod_php4.c
   AddType application/x-httpd-php .php

  If you wish to install PHP as a CGI binary, read this first:

    http://www.cert.org/advisories/CA-1996-11.html

  and then if you are really sure, insert these lines to your conf file: 

   ScriptAlias /php/ "c:/php/"
   AddType application/x-httpd-php .php
   Action application/x-httpd-php "/php/php-cgi.exe"

  Note, we consider installing PHP like this suicidal.

  As a further precaution, we recommend you change the "/php/"
  ScriptAlias to something more random, to prevent the binary being
  called directly, which is a security risk.

  Remember when you have finished to restart the server, for example,
   NET STOP APACHE
  followed by
   NET START APACHE

  To use the source code highlighting feature, add the following
  line to your apache httpd.conf file:

    AddType application/x-httpd-php-source .phps

  Note, this will only work when you install php as a sapi module.
  If you wish to use this feature with the cgi binary, create a new
  file, and use the show_source("path/to/original_file.php"); function.

  On Win-Apache all backslashes in a path statement such
  as: "c:\directory\file.ext", must be converted to
  forward slashes.

----------------------------------------------------------

 Installing PHP on Windows with IIS/PWS

  This section contains notes and hints specific to IIS (Microsoft
  Internet Information Server). Installing PHP for PWS/IIS 3 and
  PWS/IIS 4 or newer versions.

  Windows and PWS/IIS 3 - including PWS on Win 9x/ME

   The recommended method for configuring these servers is to use
   the REG file incuded with the distribution (pws-php4cgi.reg).
   You may want to edit this file and make sure the extensions and PHP
   install directories match your configuration - once you have done
   this, just double click on the file and it will update your registry.
   Alternatively, you can follow the steps below to do it manually.

   WARNING:
    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.

   Run Regedit.
   Navigate to:
    HKEY_LOCAL_MACHINE/System/CurrentControlSet/Services/W3Svc/Parameters/ScriptMap
   On the edit menu select: New->String Value.
   Type in the extension you wish to use for your php scripts. ex: .php
   Double click on the new string value and enter the path to
   php-cgi.exe in the value data field.
   ex: c:\php\php-cgi.exe
   Repeat these steps for each extension you wish to associate
   with PHP scripts.

   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 c:\myscripts\test.php) or by double
   clicking on them in a directory viewer window. You may wish to skip
   this step as you might prefer the php files to load into a text
   editor when you double click on them.

   Now navigate to: HKEY_CLASSES_ROOT
   On the edit menu select: New->Key
   Name the key to the extension you setup in the previous
   section. ex: .php
   Highlight the new key and in the right side pane, double click
   the "default value" and enter phpfile.
   Repeat the last step for each extension you set up in the
   previous section.
   Now create another New->Key under
   HKEY_CLASSES_ROOT and name it phpfile
   Highlight the new key 'phpfile' and in the
   right side pane, double click the "default value" and enter
   PHP Script.
   Right click on the 'phpfile' key and select
   New->Key, name it Shell.
   Right click on the 'Shell' key and select
   New->Key, name it open.
   Right click on the 'open' key and select
   New->Key, name it command.
   Highlight the new key 'command' and in the
   right side pane, double click the "default value" and enter
   the path to php-cgi.exe ex: c:\php\php-cgi.exe -q %1
   (don't forget the '%1').
   Exit Regedit.
   If using PWS on Windows, reboot to reload the registry.
   PWS and IIS 3 users now have a fully operational system. IIS 3
   users can use a nifty tool available at
   http://www.genusa.com/iis/iiscfg.html
   from Steven Genusa to configure their script maps.

  Windows NT/2000/XP and IIS 4 or newer and PWS 4 on NT Workstation or W2K non server editions

   To install PHP on an NT/2000/XP Server running IIS 4 or newer,
   follow these instructions. You have two options to set up
   PHP, using the CGI binary (php-cgi.exe) 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=>Administrative Tools under Windows 2000). Then
   right click on your Web server node (this will most probably
   appear as 'Default Web Server'), and select 'Properties'.

   If you want to use the CGI binary, do the following:
    Under 'Home Directory', 'Virtual Directory', or
    'Directory', click on the 'Configuration' button,
    and then enter the App Mappings tab.

    Click Add, and in the Executable box, type:
    c:\php\php-cgi.exe (assuming that you have unzipped PHP in c:\php\).

    In the Extension box, type the file name extension you want
    associated with PHP scripts. Leave 'Method exclusions'
    blank, and check the Script engine checkbox. You may also
    like to check the 'check that file exists' box - for a small
    performance penalty, IIS (or PWS) will check that the script
    file exists and sort out authentication before firing up php.
    This means that you will get sensible 404 style error messages
    instead of cgi errors complaing that php did not output any data.

    You must repeat from 'Click Add...' for each extension you
    want associated with PHP scripts.
    (.php is recommended. although .phtml and .php3 may be
    required for legacy applications.)

    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
    php-cgi.exe

   To use the ISAPI module, do the following:

    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 php4isapi.dll.

    Under 'Home Directory', click on the 'Configuration' button.
    Add a new entry to the Application Mappings. Use the path
    to the php4isapi.dll as the Executable, supply .php as the
    extension, leave Method exclusions blank, and check the
    Script engine checkbox.

    Stop IIS completely (net stop iisadmin)
    Start IIS again  (net start w3svc)

----------------------------------------------------------

 Installing PHP on Windows with OmniHTTPd Server

  This section contains notes and hints specific to
  OmniHTTPd 2.0b1 and up for Windows

  This has got to be the easiest config there is:

  Step 1: Install OmniHTTPd server.
  Step 2: Right click on the blue OmniHTTPd icon in the system
          tray and select 'Properties'
  Step 3: Click on 'Web Server Global Settings'
  Step 4: On the 'External' tab, enter:
          virtual = .php | actual = c:\path-to-php-dir\php-cgi.exe
          and use the Add button.
  Step 5: On the Mime tab, enter:
          virtual = wwwserver/stdcgi | actual = .php
          and use the Add button.
  Step 6: Click 'OK'

  Repeat steps 2 - 6 for each extension you want to associate with PHP.
  NOTE:
   Some OmniHTTPd packages come with built in PHP support.
   You can choose at setup time to do a custom setup, and
   uncheck the PHP component. We recommend you to use the latest
   PHP binaries. Some OmniHTTPd servers come with PHP 4 beta
   distributions, so you should choose not to set up
   the built in support, but install your own. If the server
   is already on your machine, use the Replace button in Step
   4 and 5 to set the new, correct information.

----------------------------------------------------------

 Installing PHP on Windows with Oreilly Website Pro

  This section contains notes and hints specific to Oreilly
  Website Pro 2.5 and up for Windows

  This list describes how to set up the PHP CGI binary
  or the ISAPI module to work with Oreilly Website Pro
  on Windows.

   Edit the Server Properties and select the tab "Mapping".

   From the List select "Associations" and enter the desired
   extension (".php") and the path to the CGI exe (ex. c:\php\php-cgi.exe)
   or the ISAPI dll file (ex. c:\php\sapi\php4isapi.dll).

   Select "Content Types" add the same extension ".php"
   and enter the content type. If you choose the CGI exe
   file, enter 'wwwserver/shellcgi', if you chose the
   ISAPI module, enter 'wwwserver/isapi' (both without quotes).

----------------------------------------------------------

 Installing PHP on Windows with Xitami

  This section contains notes and hints specific to Xitami.

  This list describes how to set up the PHP CGI binary
  to work with Xitami on Windows.

   Make sure the webserver is running, and point
   your browser to xitamis admin console
   (usually http://127.0.0.1/admin), and click on
   Configuration.

   Navigate to the Filters, and put the
   extension which php should parse (i.e. .php)
   into the field File extensions (.xxx).

   In Filter command or script put the path and name
   of your php executable i.e. c:\php\php-cgi.exe.

   Press the 'Save' icon.

----------------------------------------------------------

 Installing PHP on Windows with Netscape servers.


  To Install PHP as CGI (for Netscape Enterprise Server, iPlanet, perhaps Fastrack)

   Copy php4ts.dll to your systemroot (the directory where you installed windows)

   Make a file assocition from the command line (type the 2 following lines)
    assoc .php=PHPScript
    ftype PHPScript=c:\php\php-cgi.exe %1 %*

   In the Netscape Enterprise Administration Server create a dummy shellcgi
   directory and remove it just after (this step creates 5 important lines in
   obj.conf and allow the web server to handle shellcgi scripts)

   In the Netscape Enterprise Administration Server create a new mime type
   (Category:type,Content-Type:magnus-internal/shellcgi,File Suffix:php)

   Do it for each web server instance you want php to run

   More details http://benoit.noss.free.fr/php/install-php.html


  To Install PHP as NSAPI (for Netscape Enterprise Server, iPlanet, perhaps Fastrack)

   Copy php4ts.dll to your systemroot (the directory where you installed windows)

   Make a file assocition from the command line (type the 2 following lines)
    assoc .php=PHPScript
    ftype PHPScript=c:\php\php-cgi.exe %1 %*

   In the Netscape Enterprise Administration Server create a new mime type
    (Category:type,Content-Type:magnus-internal/x-httpd-php,File Suffix:php)

   Stop your web service and edit obj.conf
    At the end of the Init section, place these 2 lines (necessarily after mime type init!)
    Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll"
    Init fn="php4_init" errorString="Failed to initialise PHP!"

   In The < Object name="default" > section, place this line necessarily after all 'ObjectType' and before all 'AddLog' lines!
    Service fn="php4_execute" type="magnus-internal/x-httpd-php"

   At the end of the file, create a new object called x-httpd-php, by inserting this lines
    <Object name="x-httpd-php">
    ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
    Service fn=php4_execute
    </Object>

   Restart your web service and apply changes

   Do it for each web server instance you want php to run

   More details http://benoit.noss.free.fr/php/install-php4.html

----------------------------------------------------------

Problems?
=========

 Read the FAQ

  Some problems are more common than others.  The most common ones
  are listed in the PHP FAQ, found at www.php.net/FAQ.php

 Common problems with Windows

  The following problems often occur with IIS/PWS, but some points may
  also apply to other servers.

  For test purposes it is best to use just a simple test script. One
  containing just the following line will suffice:
  <?php phpinfo();?>

  You have installed PHP, but when try to access a php script file via your
  browser, you get a blank screen:

   Do a 'view source' in the web browser and you will probably find that you
   can see the source code of your php script. This means that the web server
   did not send the script to php for interpretation. Something is wrong with
   the server configuration - double check the server configuration against
   the php installation instructions.

  You have installed PHP, but when try to access a php script file via your
  browser, you get a server 500 error:

   Something went wrong when the server tried to run PHP. To get to see a
   sensible error message, from the command line, change to the directory
   containing php-cgi.exe and run <literal>php-cgi.exe -i</literal>
   If php has any problems running, then a suitable error message will be displayed
   which will give you a clue as to what needs to be done next.
   If you get a screen full of html codes (the output of the phpinfo() function) then
   php is working ok, and your problem may be related to your server configuration
   which you should double check.

  You have installed PHP, but when try to access a php script file via your
  browser, you get the error:
   cgi error:
   The specified CGI application misbehaved by not returning a complete set of
   HTTP headers. The headers it did return are:

   This error message means that php failed to output anything at all.
   From the command line hange to the directory containing php-cgi.exe. Run
   php-cgi.exe -i
   If php has any problems running, then a suitable
   error message will be displayed which will give you a clue as to what needs to
   be done next. If you get a screen full of html codes (the output of the
   phpinfo() function) then php is working ok.

   Once php is working at the command line, try accessing the php script via the browser again.
   If it still fails then it could be one of the following:

   file permissions on your php script, php-cgi.exe, php4ts.dll, php.ini or any php
   extensions you are trying to load are such that the anonymous internet user
   ISUR_<machinename> cannot access them.

   The script file does not exist (or possibly isn't where you think it is
   relative to your web root directory). Note that for IIS you can trap this error by ticking
   the 'check file exists' box when setting up the script mappings in the Internet Services
   Manager. If a script file does not exist then the server will return a 404 error instead.
   There is also the additional benefit that IIS will do any authentication required for you
   based on the NTLanMan permissions on your script file.

 Other problems
  If you are still stuck, someone on the PHP installation mailing list may be
  able to help you. You should check out the archive first, in case
  someone already answered someone else who had the same problem as
  you. The archives are available from the support page on www.php.net
  To subscribe to the PHP installation mailing list, send an empty mail to:

  php-install-subscribe@lists.php.net

  The mailing list address is php-install@lists.php.net

  If you want to get help on the mailing list, please try to be
  precise and give the necessary details about your environment
  (which operating system, what PHP version, what web server, if
  ou are running PHP as CGI or a server module, etc.), and
  referably enough code to make others able to reproduce and test
  our problem.

Bug reports
===========

 If you think you have found a bug in PHP, please report it.  The
 PHP developers probably don't know about it, and unless you
 report it, chances are it won't be fixed. You can report bugs
 using the bug-tracking system at http://bugs.php.net/

 Read the Bugs-Dos-And-Donts at
 http://bugs.php.net/bugs-dos-and-donts.php
 _BEFORE_ submitting any bug reports!