diff --git a/chapters/install.xml b/chapters/install.xml index 1c36c3864e..9a4db9ccfd 100644 --- a/chapters/install.xml +++ b/chapters/install.xml @@ -1,5 +1,5 @@ - + Installation @@ -3025,7 +3025,7 @@ $ /usr/local/sbin/php4-enable Installation on Windows systems This section applies to Windows 95/98/Me and - Windows NT/2000/XP. (On XP it is not tested currently). + Windows NT/2000/XP. (The setup is not tested currently on XP). Do not expect PHP to work on 16 bit platforms such as Windows 3.1. Sometimes we refer to the supported platforms as Win32. @@ -3054,7 +3054,9 @@ $ /usr/local/sbin/php4-enable The Windows PHP installer available from the downloads page at &url.php;, this installs the CGI version of PHP and, for IIS, PWS, and Xitami, configures the web server as - well. + well. Also note, that while the InstallShield installer is an + easy way to make PHP work, it is restricted in many aspects, as + automatic setup of extensions for example is not supported. @@ -3083,14 +3085,26 @@ $ /usr/local/sbin/php4-enable if you need to restart your system, restart the server, or just start using PHP. + + + + Be aware, that this setup of PHP is not secure. If you would + like to have a secure PHP setup, you'd better go on the manual + way, and set every option carefully. This automatically working + setup gives you an instantly working PHP installation, but it is + not meant to be used on online servers. + + - General Installation Steps + Manual Installation Steps This install guide will help you manually install and configure - PHP on your Windows webserver. The original version + PHP on your Windows webserver. You need to download the + zip binary distriobution from the downloads page at + &url.php;. The original version of this guide was compiled by &link.bob;, and can be found at &url.win32install;. @@ -3127,34 +3141,50 @@ $ /usr/local/sbin/php4-enable Xitami + + + Netscape Enterprise Server, iPlanet + + PHP 4 for Windows comes in two flavours - a CGI executable (php.exe), and several SAPI modules (for example: 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. - 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, - even though we're not aware of anyone actually running it on a - production site. 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 the Microsoft - DCOM pages. 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. - + 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, + even though we're not aware of anyone actually running it on a + production site. 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 the Microsoft DCOM pages. 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. @@ -3162,10 +3192,26 @@ $ /usr/local/sbin/php4-enable Extract the distribution file to a directory of your choice. - "C:\PHP\" is a good start. + "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.exe, + php4apache.dll). + The PHP binary, the SAPI modules, and some extensions rely on external DLLs for execution. Make sure that these DLLs in the @@ -3173,7 +3219,7 @@ $ /usr/local/sbin/php4-enable The best bet to do it is to copy the files below into your system directory, which is typically: - c:\windows\system for Windows 95/98 + c:\windows\system for Windows 9x/Me c:\winnt\system32 for Windows NT/2000 The files to copy are: @@ -3185,52 +3231,72 @@ $ /usr/local/sbin/php4-enable The files in your distribution's 'dlls' directory. If you have them already installed on your system, overwrite them only if something doesn't work correctly (Before overwriting them, - it is a good idea to make a back-up). + it is a good idea to make a backup of 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 if you use Microsoft Windows + 9x/NT4. MDAC is available at &url.mdac;. + - Copy the file, 'php.ini-dist' to your - '%WINDOWS%' directory on Windows 95/98 or to your + Copy your choosen ini file (see below) to your + '%WINDOWS%' directory on Windows 9x/Me or to your '%SYSTEMROOT%' directory under Windows NT or Windows - 2000 and rename it to 'php.ini'. Your + 2000 and rename it to php.ini. Your '%WINDOWS%' or '%SYSTEMROOT%' directory is typically: - c:\windows for Windows 95/98 + c:\windows for Windows 9x/Me c:\winnt or c:\winnt40 for NT/2000 servers + + There are two ini files distributed in the zip file, + php.ini-dist and + php.ini-optimized. We advise + you to use php.ini-optimized, + because we optimized the default settings in this + file for performance, and security. The best is to + study all the ini + settings and set every element manually yourself. + If you would like to achive the best security, then this + is the way for you, although PHP works fine with these + default ini files. + - Edit your 'php.ini' file: + Edit your new '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 + your 'php_*.dll' files. ex: c:\php\extensions 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 + document_root. For example: c:\apache\htdocs or c:\webroot Choose which extensions you would like to load when PHP - starts. You can uncomment the: 'extension=php_*.dll' lines - in php.ini to load these extensions. - You can also load a module dynamically in your script - using dl. See the section about + starts. See the section about Windows - extensions. + extensions, 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. @@ -3241,6 +3307,15 @@ $ /usr/local/sbin/php4-enable on NT/2000 Server. + + + 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.) + + @@ -3474,12 +3549,11 @@ $ /usr/local/sbin/php4-enable 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. You can - also load a module dynamically in your script using - dl. + The following table describes some of the extensions available. You + can choose which extensions you would like to load when PHP starts + by uncommenting the: 'extension=php_*.dll' lines in + php.ini. You can also load a module dynamically + in your script using dl. The DLLs for PHP extensions are prefixed with 'php_' in PHP 4 (and @@ -3489,7 +3563,7 @@ $ /usr/local/sbin/php4-enable In PHP 4.0.6 BCMath, Calendar, COM, FTP, MySQL, ODBC, PCRE, - Session, WDDX and XML support is built-in. + Session, WDDX and XML support is built in. You don't need to load any additional extensions in order to use these functions. See your distributions README.txt or install.txt @@ -3501,20 +3575,21 @@ $ /usr/local/sbin/php4-enable Some of these extensions need extra dlls to work. Couple of them can be found in the distribution package, in the 'dlls' folder but - some, e.g. Oracle (php_oci8.dll) require dlls which are not bundled - with the distribution package. + some, for example Oracle (php_oci8.dll) require dlls which are + not bundled with the distribution package. Copy the bundled dlls from 'dlls' folder to your Windows PATH, safe places are: - c:\windows\system for Windows 95/98 + c:\windows\system for Windows 9x/Me c:\winnt\system32 for Windows NT/2000 If you have them already installed on your system, overwrite them only if something doesn't work correctly (Before overwriting them, - it is a good idea to make a back-up). + it is a good idea to make a backup of them, or move them to + another folder - just in case something goes wrong). @@ -3791,7 +3866,7 @@ $ /usr/local/sbin/php4-enable Windows versions. - Details of installing PHP with Apache on Unix. + Details of installing PHP with Apache on Unix You can select arguments to add to the configure on line 8 below from the - Details of installing PHP on Windows with Apache 1.3.x + 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.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 + srm.conf or httpd.conf to configure Apache to work with PHP. @@ -3972,11 +4047,11 @@ stop and start: - If you unziped the PHP package to C:\PHP\ as described - in the General + If you unziped the PHP package to c:\php\ as described + in the Manual Installation Steps section, you need to insert - these lines to your Apache conf file to set up the - CGI binary: + these lines to your Apache configuration file to set + up the CGI binary: @@ -4000,14 +4075,18 @@ stop and start: - Remember to restart the server, for example, + Note that the second line in the list above can be found + in the actual versions of httpd.conf, + but it is commented out. After changing the configuration + file, remember to restart the server, for example, NET STOP APACHE followed by - NET START APACHE. + NET START APACHE, if you run Apache + as a Windows Service, or use your regular shortcuts. If you would like to use PHP as a module in Apache, - you should move php4ts.dll to + be sure to move php4ts.dll to the windows/system (for Windows 9x/Me) or winnt/system32 (for Windows NT/2000) directory, overwriting any older file. Then you should add the following two lines to you Apache @@ -4036,13 +4115,13 @@ stop and start: ("original_php_script.php"); ?>. Substitute original_php_script.php with the name of the file you wish to show the source of. (This is the only way of - doing so). + doing this, as there is no .phps like feature on Windows). On Win-Apache all backslashes in a path statement such - as: "c:\directory\file.ext", must be converted to - forward slashes. + as "c:\directory\file.ext", must be converted to + forward slashes, as "c:/directory/file.ext". @@ -4163,7 +4242,7 @@ stop and start: Servers-IIS/PWS This section contains notes and hints specific to IIS (Microsoft - Internet Information Server) installing PHP for + Internet Information Server). Installing PHP for PWS/IIS 3, PWS 4 or newer and IIS 4 or newer versions. @@ -4173,8 +4252,8 @@ stop and start: The recommended method for configuring these servers is to use - the INF file included with the distribution - (php_iis_reg.inf). You may want to edit this file and make sure + the REG file included 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. Or you can follow the steps below to do it manually. @@ -4211,15 +4290,14 @@ stop and start: Type in the extension you wish to use for your php - scripts. ex: .php + scripts. For example .php Double click on the new string value and enter the path to php.exe in the value data field. ex: - c:\php\php.exe %s %s. The '%s %s' is VERY - important, PHP will not work properly without it. + c:\php\php.exe. @@ -4228,9 +4306,22 @@ stop and start: 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 these + steps 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 + Navigate to: HKEY_CLASSES_ROOT @@ -4335,7 +4426,7 @@ stop and start: Edit the enclosed pws-php4cgi.reg file (look into the sapi dir) to reflect the location of your php.exe. Forward slashes should be escaped, for example: - [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="C:\\PHP\\php.exe" + [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="c:\\php\\php.exe" @@ -4356,7 +4447,7 @@ stop and start: Edit the enclosed pws-php4isapi.reg file (look into the sapi dir) to reflect the location of your php4isapi.dll. Forward slashes should be escaped, for example: - [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="C:\\PHP\\sapi\\php4isapi.dll" + [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="c:\\php\\sapi\\php4isapi.dll" @@ -4402,21 +4493,27 @@ stop and start: Click Add, and in the Executable box, type: - c:\php\php.exe %s %s (assuming - that you have unziped PHP in c:\php\). You MUST - have the %s %s on the end, PHP will not function - properly if you fail to do this. + c:\php\php.exe (assuming + that you have unziped 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 must repeat step 3 and 4 for each extension you - want associated with PHP scripts. - (.php and .phtml - are common.) + 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 start over from the previous step for each + extension you want associated with PHP scripts. + .php and .phtml + are common, although .php3 may be + required for legacy applications. @@ -4445,19 +4542,19 @@ stop and start: 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. + 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 + Stop IIS completely (NET STOP iisadmin) - Start IIS again + Start IIS again (NET START w3svc) @@ -4468,19 +4565,24 @@ stop and start: Servers-Netscape and iPlanet - To build PHP with NES or iPlanet web servers, enter the proper - install directory for the - - option. The default directory is usually - /opt/netscape/suitespot/. - Please also read /php-xxx-version/sapi/nsapi/nsapi-readme.txt. + This section contains notes and hints specific to Netscape and iPlanet + installs of PHP, both for Sun Solaris + and Windows versions. - - - - Installation Example for Netscape Enterprise on Solaris - - + + Installing PHP with Netscape on Sun Solaris + + To build PHP with NES or iPlanet web servers, enter the proper + install directory for the + option. The default + directory is usually /opt/netscape/suitespot/. + Please also read /php-xxx-version/sapi/nsapi/nsapi-readme.txt. + + + + Installation Example for Netscape Enterprise on Solaris + Instructions for Sun Solaris 2.6 with Netscape Enterprise Server 3.6 From: bhager@invacare.com @@ -4532,12 +4634,12 @@ download site: located in:/path/to/server/https-servername/config/. - - - - Configuration Example for Netscape Enterprise - - + + + + Configuration Example for Netscape Enterprise + + Configuration Instructions for Netscape Enterprise Server From: bhager@invacare.com @@ -4590,7 +4692,9 @@ From: bhager@invacare.com </Object> - If you are running Netscape Enterprise 4.x, then you should use the following: + + If you are running Netscape Enterprise 4.x, then you should use the following: + Configuration Example for Netscape Enterprise 4.x @@ -4602,6 +4706,134 @@ Init fn="load-modules" shlib="/path/to/server4/bin/libphp4.so" funcs="php4_init, Init fn="php4_init" LateInit="yes" + + + Installing PHP with Netscape on Windows + + To Install PHP as CGI (for Netscape Enterprise Server, + iPlanet, perhaps Fastrack), do the following: + + + + + Copy php4ts.dll to your systemroot + (the directory where you installed windows) + + + + + Make a file association from the command line. + Type the following two lines: + +assoc .php=PHPScript +ftype PHPScript=c:\php\php.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 about setting up + PHP as a CGI executable can be found here: + &url.netscape.cgi; + + + To Install PHP as NSAPI (for Netscape Enterprise Server, + iPlanet, perhaps Fastrack, do the following: + + + + + Copy php4ts.dll to your systemroot + (the directory where you installed windows) + + + + + Make a file association from the command line. + Type the following two lines: + +assoc .php=PHPScript +ftype PHPScript=c:\php\php.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 two 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 these 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 about setting up + PHP as an NSAPI filter can be found here: + &url.netscape.nsapi; + + @@ -4613,7 +4845,11 @@ Init fn="php4_init" LateInit="yes" OmniHTTPd 2.0b1 and up for Windows - This has got to be the easiest config there is: + You need to complete the folowing steps to make PHP + work with OmniHTTPd. This is a CGI executable setup. + SAPI is supported by OmniHTTPd, but some tests showed, + that it is not so stable to use PHP as an ISAPI module + in OmniHTTPd. @@ -4699,18 +4935,18 @@ Init fn="php4_init" LateInit="yes" From the List select "Associations" and enter the desired - extension (".php") and the path to the CGI exe - (ex. c:\php\php.exe) or the ISAPI dll file - (ex. c:\php\sapi\php4isapi.dll). + extension (.php) and the path to the CGI exe + (ex. c:\php\php.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 chosse the - ISAPI module, enter 'wwwserver/isapi' (both without - quotes). + Select "Content Types" add the same extension + (.php) and enter the content type. + If you choose the CGI executable file, enter + 'wwwserver/shellcgi', if you chosse the ISAPI module, + enter 'wwwserver/isapi' (both without quotes). @@ -4737,21 +4973,21 @@ Init fn="php4_init" LateInit="yes" 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. + (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) + 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.exe. + of your php executable i.e. c:\php\php.exe.