diff options
Diffstat (limited to 'win32')
| -rw-r--r-- | win32/install.txt | 2088 |
1 files changed, 1364 insertions, 724 deletions
diff --git a/win32/install.txt b/win32/install.txt index 598db86cb4..152044a781 100644 --- a/win32/install.txt +++ b/win32/install.txt @@ -1,801 +1,1441 @@ -PHP/Windows Installation Notes -============================== - -Installation on Windows 9x/Me/NT/2000/XP/2003 systems -===================================================== - -There are two main ways to install PHP for Windows: either -manually or by using the installer. +Installing PHP + _________________________________________________________________ + + Table of Contents + 1. General Installation Considerations + 2. Installation on Windows systems + + Windows Installer + Manual Installation Steps + ActiveScript + Microsoft IIS / PWS + Apache 1.3.x on Microsft Windows + Apache 2.0.x on Microsoft Windows + Sun, iPlanet and Netscape servers on Microsoft Windows + OmniHTTPd Server + Sambar Server on Microsoft Windows + Xitami on Microsoft Windows + Installation of extensions on Windows + + 3. Problems? + + Read the FAQ + Other problems + Bug reports + + 4. Runtime Configuration + + The configuration file + How to change configuration settings + _________________________________________________________________ + +Chapter 1. General Installation Considerations + + Before starting the installation, first you need to know what do you + want to use PHP for. There are three main fields you can use PHP, as + described in the What can PHP do? section: + + * Server-side scripting + * Command line scripting + * Client-side GUI applications + + For the first and most common form, you need three things: PHP itself, + a web server and a web browser. You probably already have a web + browser, and depending on your operating system setup, you may also + have a web server (e.g. Apache on Linux and MacOS X; IIS on Windows). + You may also rent webspace at a company. This way, you don't need to + set up anything on your own, only write your PHP scripts, upload it to + the server you rent, and see the results in your browser. + + While setting up the server and PHP on your own, you have two choices + for the method of connecting PHP to the server. For many servers PHP + has a direct module interface (also called SAPI). These servers + include Apache, Microsoft Internet Information Server, Netscape and + iPlanet servers. Many other servers have support for ISAPI, the + Microsoft module interface (OmniHTTPd for example). If PHP has no + module support for your web server, you can always use it as a CGI or + FastCGI processor. This means you set up your server to use the CGI + executable of PHP to process all PHP file requests on the server. + + If you are also interested to use PHP for command line scripting (e.g. + write scripts autogenerating some images for you offline, or + processing text files depending on some arguments you pass to them), + you always need the command line executable. For more information, + read the section about writing command line PHP applications. In this + case, you need no server and no browser. + + With PHP you can also write desktop GUI applications using the PHP-GTK + extension. This is a completely different approach than writing web + pages, as you do not output any HTML, but manage windows and objects + within them. For more information about PHP-GTK, please visit the site + dedicated to this extension. PHP-GTK is not included in the official + PHP distribution. + + From now on, this section deals with setting up PHP for web servers on + Unix and Windows with server module interfaces and CGI executables. + You will also find information on the command line executable in the + following sections. + + PHP source code and binary distributions for Windows can be found at + http://www.php.net/downloads.php. We recommend you to choose a mirror + nearest to you for downloading the distributions. + _________________________________________________________________ + +Chapter 2. Installation on Windows systems + + This section applies to Windows 98/Me and Windows NT/2000/XP/2003. PHP + will not work on 16 bit platforms such as Windows 3.1 and sometimes we + refer to the supported Windows platforms as Win32. Windows 95 is no + longer supported as of PHP 4.3.0. + + There are two main ways to install PHP for Windows: either manually or + by using the installer. + + If you have Microsoft Visual Studio, you can also build PHP from the + original source code. + + Once you have PHP installed on your Windows system, you may also want + to load various extensions for added functionality. + + Warning + + There are several all-in-one installers over the Internet, but none of + those are endorsed by PHP.net, as we believe that the manual + installation is the best choice to have your system secure and + optimised. + _________________________________________________________________ Windows Installer -================= - - 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 - Apache 2.0.x (experimental) - OmniHTTPd 2.0b1 and up - Oreilly Website Pro - Xitami - SunONE Webserver, Netscape Enterprise Server, iPlanet - - PHP for Windows comes in two flavours - a CGI executable (php-cgi.exe), - and several SAPI modules (for exapmle php5isapi.dll). The latter form - is new to PHP, 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, 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. php5ts.dll is always used. - To make sure that the dlls can be found, you can add your PHP folder - (ex: c:\php) to your system PATH. Alternatively 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, - php5apache.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 - We will refer to %SYSTEMROOT% for both %WINDOWS% or - %SYSTEMROOT% throughout the text. - - 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\ext - - 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. - - In order for PHP to be able to find them they need to be located - in a directory that is included in the system PATH. The recommended - way to do this is to add PHP installation folder (ex: c:\php) to your - PATH. - - Alternatively you can copy the bundled dlls from the root 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: - Since PHP 5.0.0 bcmath, calendar, com_dotnet, ctype, dom, ftp, - iconv, odbc, pcre, session, SimpleXML, SPL, SQLite, tokenizer, - wddx, xml and zlib extensions are 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_gd2.dll GD library functions for image 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!) - - 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 - ------------------------------------------------------------ - ATTENTION: Apache 2 Users + The Windows PHP installer is available from the downloads page at + http://www.php.net/downloads.php. This installs the CGI version of PHP + and for IIS, PWS, and Xitami, it configures the web server as well. + The installer does not include any extra external PHP extensions + (php_*.dll) as you'll only find those in the Windows Zip Package and + PECL downloads. + + Note: While the Windows installer is an easy way to make PHP work, + it is restricted in many aspects as, for example, the automatic + setup of extensions is not supported. Use of the installer isn't + the preferred method for installing PHP. + + First, install your selected HTTP (web) 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 certain web servers to use PHP. With IIS + or PWS on a 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. One of the web servers + the PHP installer does not configure for is Apache, so you'll need to + configure it manually. + + 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. + + Warning + + 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. + _________________________________________________________________ + +Manual Installation Steps + + 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 + http://www.php.net/downloads.php. + + 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. + + Upgrading from a previous PHP version: Previous editions of the + manual suggest moving various ini and DLL files into your SYSTEM + (i.e. C:\WINDOWS) 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. + + MDAC requirements: If you use Microsoft Windows 98/NT4 download the + latest version of the Microsoft Data Access Components (MDAC) for + your platform. MDAC is available at + http://msdn.microsoft.com/data/. This requirement exists because + ODBC is built into the distributed Windows binaries. + + The following steps should be completed on all installations before + any server specific instructions are performed: + + Extract the distribution file into a directory of your choice. If you + are installing PHP 4, extract to C:\, as the zip file expands to a + foldername like php-4.3.7-Win32. If you are installing PHP 5, extract + to C:\php 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 C:\Program + Files\PHP) as some web servers will crash if you do. + + The directory structure extracted from the zip is different for PHP + versions 4 and 5 and look like as follows: + + Example 2-1. PHP 4 package structure +c:\php + | + +--cli + | | + | |-php.exe -- CLI executable - ONLY for commandline 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 + | | + | |-php4activescript.dll + | | + | |-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 + | + |-... + + Or: + + Example 2-2. PHP 5 package structure +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 + | + |-... + + Notice the differences and similarities. Both PHP 4 and PHP 5 have a + CGI executable, a CLI 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 sapi 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. + + Note: In PHP 4, you should move all files located in the dll and + sapi folders to the main folder (e.g. C:\php). + + Here is a list of server modules shipped with PHP 4 and PHP 5: + + * sapi/php4activescript.dll (php5activescript.dll) - ActiveScript + engine, allowing you to embed PHP in your Windows applications. + * sapi/php4apache.dll (php5apache.dll) - Apache 1.3.x module. + * sapi/php4apache2.dll (php5apache2.dll) - Apache 2.0.x module. + * sapi/php4isapi.dll (php5isapi.dll) - ISAPI Module for ISAPI + compliant web servers like IIS 4.0/PWS 4.0 or newer. + * sapi/php4nsapi.dll (php5nsapi.dll) - Sun/iPlanet/Netscape server + module. + * sapi/php4pi3web.dll (no equivalent in PHP 5) - Pi3Web server + module. + + 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 using PHP from the command line. + + Warning + + 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. + + The CGI and CLI binaries, and the web server modules all require the + php4ts.dll (php5ts.dll) 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: + + * The same directory from where php.exe is called, or in case you + use a SAPI module, the web server's directory (e.g. C:\Program + Files\Apache Group\Apache2\bin). + * Any directory in your Windows PATH environment variable. + + To make php4ts.dll / php5ts.dll 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, C:\php to the PATH. For + better maintenance, we advise you to follow the last option, add + C:\php to the PATH, because it will be simpler to upgrade PHP in the + future. Read more about how to add your PHP directory to PATH in the + corresponding FAQ entry. + + 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, + php.ini-dist and php.ini-recommended. We advise you to use + php.ini-recommended, because we optimized the default settings in this + file for performance, and security. Read this well documented file + carefully because it has changes from php.ini-dist that will + drastically affect your setup. Some examples are display_errors being + off and magic_quotes_gpc being off. In addition to reading these, + study the ini settings 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 following locations (in + order): + + * PHPIniDir directive (Apache 2 module only) + * HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath + * The PHPRC environment variable + * Directory of PHP (for CLI), or the web server's directory (for + SAPI modules) + * Windows directory (C:\windows or C:\winnt) + + If you are running Apache 2, the simpler option is to use the + PHPIniDir directive (read the installation on Apache 2 page), + otherwise your best option is to set the PHPRC environment variable. + This process is explained in the following FAQ entry. + + Note: 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). + + The following steps are optional: + + * Edit your new php.ini file. If you plan to use OmniHTTPd, do not + follow the next step. Set the doc_root to point to your web + servers document_root. For example: + +doc_root = c:\inetpub // for IIS/PWS + +doc_root = c:\apache\htdocs // for Apache + + * Choose the extensions you would like to load when PHP starts. See + the section about Windows 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. + * On PWS and IIS, you can set the browscap configuration setting to + point to: c:\windows\system\inetsrv\browscap.ini on Windows 9x/Me, + c:\winnt\system32\inetsrv\browscap.ini on NT/2000, and + c:\windows\system32\inetsrv\browscap.ini on XP. For an up-to-date + browscap.ini, read the following FAQ. + + PHP is now setup on your system. The next step is to choose a web + server, and enable it to run PHP. Choose a webserver from the table of + contents. + _________________________________________________________________ + +ActiveScript + + This section contains notes specific to the ActiveScript installation. + + ActiveScript is a windows only SAPI that enables you to use PHP script + in any ActiveScript compliant host, like Windows Script Host, + ASP/ASP.NET, Windows Script Components or Microsoft Scriptlet control. + + As of PHP 5.0.1, ActiveScript has been moved to the PECL repository. + You may download this PECL extensions DLL from the PHP Downloads page + or at http://snaps.php.net/. + + Note: You should read the manual installation steps first! + + After installing PHP, you should download the ActiveScript DLL + (php5activescript.dll) and place it in the main PHP folder (e.g. + C:\php). + + After having all the files needed, you must register the DLL on your + system. To achieve this, open a Command Prompt window (located in the + Start Menu). Then go to your PHP directory by typing something like cd + C:\php. To register the DLL just type regsvr32 php5activescript.dll. + + To test if ActiveScript is working, create a new file, named test.wsf + (the extension is very important) and type: +<job id="test"> + + <script language="PHPScript"> + $WScript->Echo("Hello World!"); + </script> + +</job> + + Save and double-click on the file. If you receive a little window + saying "Hello World!" you're done. + + Note: ActiveScript doesn't use the default php.ini file. Instead, + it will look only in the same directory as the .exe that caused it + to load. You should create php-activescript.ini and place it in + that folder, if you wish to load extensions, etc. + _________________________________________________________________ + +Microsoft IIS / PWS + + This section contains notes and hints specific to IIS (Microsoft + Internet Information Server). We have included installation + instructions for PWS/IIS 3, PWS 4 or newer and IIS 4 or newer + versions. + + Important for CGI users: Read the faq on cgi.force_redirect for + important details. This directive needs to be set to 0. - At this time, support for Apache 2 is experimental. It's - highly recommended you use PHP with Apache 1.3.x and not - Apache 2. Documentation for installing Apache 2 on windows - can be seen here: + Warning - http://www.php.net/manual/en/install.apache2.php + By using the CGI setup, your server is open to several possible + attacks. Please read our CGI security section to learn how to defend + yourself from those attacks. + _________________________________________________________________ - With the basic difference being that when installing as a - module you'll use php5apache2.dll instead of php5apache.dll - Both files are included within this release. - ------------------------------------------------------------ +Windows and PWS/IIS 3 + The recommended method for configuring these servers is to use the REG + file included with the distribution (pws-php4cgi.reg in the SAPI + folder for PHP 4, or pws-php5cgi.reg 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. + + 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. 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 for PHP 4, or + C:\php\php-cgi.exe for PHP 5. + * Repeat these steps for each extension you wish to associate with + PHP scripts. - 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 - httpd.conf or srm.conf to configure Apache to work with PHP. - We'll refer to either of these files with httpd.conf in the - text. - - 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. + 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. + * 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.exe. ex: + c:\php\php.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 from Steven Genusa to configure their script + maps. + _________________________________________________________________ + +Windows and PWS 4 or newer + + When installing PHP on Windows with PWS 4 or newer version, you have + two options. One to set up the PHP CGI binary, the other is to use the + ISAPI module DLL. + + If you choose the CGI binary, do the following: + + * Edit the enclosed pws-php4cgi.reg / pws-php5cgi.reg file (look + into the SAPI folder for PHP 4, or in the main folder for PHP 5) + to reflect the location of your php.exe / php-cgi.exe. Backslashes + should be escaped, for example: + [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parame + ters\Script Map] ".php"="C:\\php\\php.exe" (change to + C:\\php\\php-cgi.exe if you are using PHP 5) Now merge this + registery file into your system; you may do this by + double-clicking it. + * 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. + + If you choose the ISAPI module, do the following: + + * Edit the enclosed pws-php4isapi.reg / pws-php5isapi.reg file (look + into the SAPI folder for PHP 4, or in the main folder for PHP 5) + to reflect the location of your php4isapi.dll / php5isapi.dll. + Backslashes should be escaped, for example: + [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parame + ters\Script Map] ".php"="C:\\php\\sapi\\php4isapi.dll" (or + C:\\php\\php5isapi.dll for PHP 5) Now merge this registery file + into your system; you may do this by double-clicking it. + * 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. + _________________________________________________________________ + +Windows NT/2000/XP and IIS 4 or newer + + 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.exe in PHP 4, or php-cgi.exe in PHP 5) 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/XP). Then right click on your Web server node (this + will most probably appear as 'Default Web Server'), and select + 'Properties'. - Installing PHP for Apache as module - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If you want to use the CGI binary, do the following: - Now that version 4.1 introduces a safer sapi module, we recommend - that you configure PHP as a module in Apache. + * 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.exe for PHP + 4 or C:\php\php-cgi.exe for PHP 5 (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 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 + complaining 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. + * 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.exe / + php-cgi.exe. - To accomplish this, you have to load the php5apache.dll in your - Apache httpd.conf. + To use the ISAPI module, do the following: - !! NOTE !! - Whereever you load php5apache.dll from, php5apache.dll also - needs the php5ts.dll also included in the PHP distribution. - php5apache.dll depends on php5ts.dll which is loaded as soon as - Apache loads php5apache.dll. If php5ts.dll can't be found, you - usually get an error like (also see the "Problems?" section at - the end of the file): + * 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 / php5isapi.dll. + * Under 'Home Directory', click on the 'Configuration' button. Add a + new entry to the Application Mappings. Use the path to the + php4isapi.dll / php5isapi.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) + _________________________________________________________________ + +Apache 1.3.x on Microsft Windows + + This section contains notes and hints specific to Apache 1.3.x + installs of PHP on Microsoft Windows systems. We also have + instructions and notes for Apache 2 on a separate page. + + Note: You should read the manual installation steps first! - Cannot load c:/php/php5apache.dll into server + 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 for PHP 4 and php-cgi.exe for + PHP 5), the other is to use the Apache module DLL. In either case you + need to edit your httpd.conf to configure Apache to work with PHP, and + then restart the server. - So where does php5ts.dll has to be to be properly loaded ? - php5ts.dll is searched in the following order: + It is worth noting here that now the SAPI module has been made more + stable under Windows, we recommend it's use above the CGI binary, + since it is more transparent and secure. - 1) in the directory where apache.exe is start from - 2) in the directory where php5apache.dll is loaded from - 3) in your %SYSTEMROOT%\System32, %SYSTEMROOT%\system and - %SYSTEMROOT% directory. - Note: %SYSTEMROOT%\System32 only applies to Windows NT/2000/XP) - 4) in your whole %PATH% + 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 Documentation for further configuration directives. - Note: What is %SYSTEMROOT% ? Depending on your Windows - installation this may be for example c:\winnt or C:\windows + After changing the configuration file, remember to restart the server, + for example, NET STOP APACHE followed by NET START APACHE, if you run + Apache as a Windows Service, or use your regular shortcuts. - Usually you would just copy it over to %SYSTEMROOT%\System32. - But if you want to have multiple PHP installations (for - whatever reason) this is a bad idea. For this circumstance the - safest thing is to let php5ts.dll reside in the same directory - where php5apache.dll is loaded from (see point 2 above). + Note: Remember that when adding path values in the Apache + configuration files on Windows, all backslashes such as + c:\directory\file.ext must be converted to forward slashes, as + c:/directory/file.ext. + _________________________________________________________________ +Installing as a CGI binary - After you've set up the file layout properly, you're ready to - finally configure Apache to load the PHP module. Just add the - following lines to your httpd.conf: + 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 configuration file to set up the CGI binary: - LoadModule php5_module c:/php/php5apache.dll - AddModule mod_php5.c - AddType application/x-httpd-php .php + Example 2-3. PHP and Apache 1.3.x as CGI +ScriptAlias /php/ "c:/php/" +AddType application/x-httpd-php .php - Note: Especially newer versions of Apache do not need the - AddModule directive anymore, your milage may vary. +# For PHP 4 +Action application/x-httpd-php "/php/php.exe" +# For PHP 5 +Action application/x-httpd-php "/php/php-cgi.exe" - Where do I have to put the php.ini ? - The php.ini files is only searched in two places: - 1) in your Apache installation directory (e.g. c:\apache\apache) - 2) in your %SYSTEMROOT% directory. - +# specify the directory where php.ini is +SetEnv PHPRC C:/php - Installing PHP for Apache as CGI binary - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Note that the second line in the list above can be found in the actual + versions of httpd.conf, but it is commented out. Remember also to + substitute the c:/php/ for your actual path to PHP. - If you wish to install PHP as a CGI binary, read this first: + Warning - http://www.cert.org/advisories/CA-1996-11.html + By using the CGI setup, your server is open to several possible + attacks. Please read our CGI security section to learn how to defend + yourself from those attacks. - and then if you are really sure, insert these lines to your conf file: + If you would like to present PHP source files syntax highlighted, + there is no such convinient option as with the module version of PHP. + If you chose to configure Apache to use PHP as a CGI binary, you will + need to use the show_source() function. To do this simply create a PHP + script file and add this code: <?php + show_source("original_php_script.php"); ?>. Substitute + original_php_script.php with the name of the file you wish to show the + source of. + _________________________________________________________________ - ScriptAlias /php/ "c:/php/" - AddType application/x-httpd-php .php - Action application/x-httpd-php "/php/php-cgi.exe" +Installing as an Apache module - Note, we consider installing PHP like this suicidal. + You should add the following lines to your Apache httpd.conf file: - 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. + Example 2-4. PHP as an Apache 1.3.x module +AddType application/x-httpd-php .php - Remember when you have finished to restart the server, for example, - NET STOP APACHE - followed by - NET START APACHE +# For PHP 4 +LoadModule php4_module "c:/php/sapi/php4apache.dll" - To use the source code highlighting feature, add the following - line to your apache httpd.conf file: +# For PHP 5 +LoadModule php5_module "c:/php/php5apache.dll" - AddType application/x-httpd-php-source .phps +# specify the directory where php.ini is +SetEnv PHPRC C:/php - 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. + You may find after using the Windows installer for Apache that you + need to define the AddModule directive for mod_php4.c. This is + especially important if the ClearModuleList directive is defined, + which you will find by scrolling down a few lines. You will see a list + of AddModule entries, add the following line at the end of the list: + AddModule mod_php4.c. For PHP 5, instead use AddModule mod_php5.c + If you would like to use the source code highlighting feature, you + need to add the following line to your httpd.conf: AddType + application/x-httpd-php-source .phps. This should be inserted at the + same place where you inserted AddType application/x-httpd-php .php + above). With this setup, all files served with the .phps extension + will be syntax highlighted for the browser. + _________________________________________________________________ - Forward or backslash in pathnames ? - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - On Win-Apache, path names can contain either forward- or backslashes. - Example: +Apache 2.0.x on Microsoft Windows - LoadModule php5_module C:\php\php5apache.dll + This section contains notes and hints specific to Apache 2.0.x + installs of PHP on Microsoft Windows systems. We also have + instructions and notes for Apache 1.3.x users on a separate page. - works as good as + Note: You should read the manual installation steps first! - LoadModule php5_module C:/php/php5apache.dll + Warning - You even can mix the slash-style: + Do not use Apache 2.0.x and PHP in a production environment neither on + Unix nor on Windows. For information on why, read the following FAQ + entry - LoadModule php5_module C:\php/php5apache.dll + You are highly encouraged to take a look at the Apache Documentation + to get a basic understanding of the Apache 2.0.x Server. Also consider + to read the Windows specific notes for Apache 2.0.x before reading on + here. ----------------------------------------------------------- + PHP and Apache 2.0.x compatibility notes: The following versions of + PHP are known to work with the most recent version of Apache 2.0.x: - Installing PHP on Windows with IIS/PWS + * PHP 4.3.0 or later available at http://www.php.net/downloads.php. + * the latest stable development version. Get the source code + http://snaps.php.net/php4-latest.tar.gz or download binaries for + Windows http://snaps.php.net/win32/php4-win32-latest.zip. + * a prerelease version downloadable from http://qa.php.net/. + * you have always the option to obtain PHP through anonymous CVS. - 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. + These versions of PHP are compatible to Apache 2.0.40 and later. - Windows and PWS/IIS 3 - including PWS on Win 9x/ME + Apache 2.0 SAPI-support started with PHP 4.2.0. PHP 4.2.3 works + with Apache 2.0.39, don't use any other version of Apache with PHP + 4.2.3. However, the recommended setup is to use PHP 4.3.0 or later + with the most recent version of Apache2. - The recommended method for configuring these servers is to use - the REG file incuded with the distribution (pws-php5cgi.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. + All mentioned versions of PHP will work still with Apache 1.3.x. - 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. + Warning - 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'. + Apache 2.0.x is designed to run on Windows NT 4.0, Windows 2000 or + Windows XP. At this time, support for Windows 9x is incomplete. Apache + 2.0.x is not expected to work on those platforms at this time. - 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. + Download the most recent version of Apache 2.0.x and a fitting PHP + version. Follow the Manual Installation Steps and come back to go on + with the integration of PHP and Apache. - Click Add, and in the Executable box, type: - c:\php\php-cgi.exe (assuming that you have unzipped PHP in c:\php\). + There are two ways to set up PHP to work with Apache 2.0.x on Windows. + One is to use the CGI binary the other is to use the Apache module + DLL. In either case you need to edit your httpd.conf to configure + Apache to work with PHP and then restart the server. - 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. + Note: Remember that when adding path values in the Apache + configuration files on Windows, all backslashes such as + c:\directory\file.ext must be converted to forward slashes, as + c:/directory/file.ext. + _________________________________________________________________ - 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.) +Installing as a CGI binary - 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 + You need to insert these three lines to your Apache httpd.conf + configuration file to set up the CGI binary: - !NOTE!: Since 4.1.2, the php.ini setting cgi.force_redirect defaults to '1' - which effectively prevents the cgi from working within IIS. You need to set - up at least a minimal php.ini file with the following directive: + Example 2-5. PHP and Apache 2.0 as CGI +ScriptAlias /php/ "c:/php/" +AddType application/x-httpd-php .php - cgi.force_redirect = 0 +# For PHP 4 +Action application/x-httpd-php "/php/php.exe" - If it doesn't work immidiately, make sure you have the php.ini file in the - right place (%SYSTEMROOT%\php.ini). +# For PHP 5 +Action application/x-httpd-php "/php/php-cgi.exe" + Warning - To use the ISAPI module, do the following: + By using the CGI setup, your server is open to several possible + attacks. Please read our CGI security section to learn how to defend + yourself from those attacks. + _________________________________________________________________ - 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 php5isapi.dll. +Installing as an Apache module - Under 'Home Directory', click on the 'Configuration' button. - Add a new entry to the Application Mappings. Use the path - to the php5isapi.dll as the Executable, supply .php as the - extension, leave Method exclusions blank, and check the - Script engine checkbox. + You need to insert these two lines to your Apache httpd.conf + configuration file to set up the PHP module for Apache 2.0: - Stop IIS completely (net stop iisadmin) - Start IIS again (net start w3svc) + Example 2-6. PHP and Apache 2.0 as Module +# For PHP 4 do something like this: +LoadModule php4_module "c:/php/sapi/php4apache2.dll" +AddType application/x-httpd-php .php ----------------------------------------------------------- - - 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\php5isapi.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/iPlanet/SunONE servers. - - - These instructions are targetted at Netscape Enterprise Web Server and - SUN/Netscape Alliance iPlanet Web Server/SunONE Webserver. - On other web servers your milage may vary. - - Netscape/iPlanet/SunONE config files are located in: - - <path-to-server>\https-servername\config - - - Add the following line to mime.types (you can do that by the administration server): - - type=magnus-internal/x-httpd-php exts=php - - - Place the following two lines after mime.types init in - <path-to-server>\https-servername\config\obj.conf (for servers < 6) or - for iPlanet/SunONE Web Server 6.0 and above however at the end of the - <path-to-server>\https-servername\config\magnus.conf file: - - Init fn="load-modules" funcs="php5_init,php5_execute,php5_auth_trans" shlib="c:/path/to/PHP/php5nsapi.dll" - Init fn=php5_init errorString="Failed to initialize PHP!" [php_ini="c:/path/to/php.ini"] - - In obj.conf (for virtual server classes [SunONE 6.0+] in their vserver.obj.conf): - - <Object name="default"> - . - . - . - # NOTE this next line should happen after all 'ObjectType' and before - # all 'AddLog' lines - # You can modify some entries in php.ini request specific by adding it to the Service - # directive, e.g. doc_root="/path" - # For boolean ini-keys please use 0/1 as value, NOT "On","Off",... (this will not work - # correctly), e.g. zlib.output_compression=1 instead of zlib.output_compression="On" - - Service fn="php5_execute" type="magnus-internal/x-httpd-php" [inikey=value ...] - . - . - . - </Object> - - This is only needed if you want to configure a directory that only consists of - PHP scripts (same like a cgi-bin directory): - - <Object name="x-httpd-php"> - ObjectType fn="force-type" type="magnus-internal/x-httpd-php" - Service fn="php5_execute" [inikey=value ...] - </Object> - - After that you can configure a directory in the Administration server and assign it - the style "x-httpd-php". All files in it will get executed as PHP. This is nice to - hide PHP usage by renaming files to .html - ----------------------------------------------------------- - - Installing PHP on The Sambar Server - - This section contains notes and hints specific to Sambar - - Find the file called mappings.ini (config directory) in your Sambar - install directory - - Open mappings.ini and add the following line under [isapi] - - *.php = c:\php\php5isapi.dll - Note: The above assumes that PHP was installed in c:\php - - Restart the server - ----------------------------------------------------------- - -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 "php-cgi.exe -i" (without quotes). - 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, php5ts.dll, php.ini or any php - extensions you are trying to load are such that the web server cannot access - them. For IIS, IUSR_<machinename> needs at least read access. - - 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. +# For PHP 5 do something like this: +LoadModule php5_module "c:/php/php5apache2.dll" +AddType application/x-httpd-php .php +# configure the path to php.ini +PHPIniDir "C:/php" - You have inherent problems loading the right DLL? - Sometimes, loading the right DLL can be a pain on Windows. - Advanced Windows users may use a tool called strace (named - after the famous Unix application) to trace file access on the - system (however, it only works on NT-alike Windows, read: - NT/2000/XP). It can be found at - http://razor.bindview.com/tools/desc/strace_readme.html . Read - the instruction there carefully! + Note: Remember to substitute the c:/php/ for your actual path to + PHP in the above examples. Take care to use either php4apache2.dll + or php5apache2.dll in your LoadModule directive and not + php4apache.dll or php5apache.dll as the latter ones are designed to + run with Apache 1.3.x. - Example scenery: + Warning - Apache/PHP as module. Though I've properly configured - php5apache.dll in httpd.conf, I always get: + Don't mix up your installation with DLL files from different PHP + versions. You have the only choice to use the DLL's and extensions + that ship with your downloaded PHP version. + _________________________________________________________________ + +Sun, iPlanet and Netscape servers on Microsoft Windows + + This section contains notes and hints specific to Sun Java System Web + Server, Sun ONE Web Server, iPlanet and Netscape server installs of + PHP on Windows. + + From PHP 4.3.3 on you can use PHP scripts with the NSAPI module to + generate custom directory listings and error pages. Additional + functions for Apache compatibility are also available. For support in + current webservers read the note about subrequests. + _________________________________________________________________ + +CGI setup on Sun, iPlanet and Netscape servers + + To install PHP as a CGI handler, 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: http://benoit.noss.free.fr/php/install-php.html + _________________________________________________________________ + +NSAPI setup on Sun, iPlanet and Netscape servers + + To install PHP with NSAPI, 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). + * Edit magnus.conf (for servers >= 6) or obj.conf (for servers < 6) + and add the following: You should place the lines after mime types + init. + +Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="c: +/php/sapi/php4nsapi.dll" +Init fn="php4_init" LateInit="yes" errorString="Failed to initialise PHP!" [php +_ini="c:/path/to/php.ini"] + + (PHP >= 4.3.3) The php_ini parameter is optional but with it you + can place your php.ini in your webserver config directory. + * Configure the default object in obj.conf (for virtual server + classes [Sun Web Server 6.0+] in their vserver.obj.conf): 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" [inikey=value inik +ey=value ...] + + (PHP >= 4.3.3) As additional parameters you can add some special + php.ini-values, for example you can set a + docroot="/path/to/docroot" specific to the context php4_execute is + called. For boolean ini-keys please use 0/1 as value, not + "On","Off",... (this will not work correctly), e.g. + zlib.output_compression=1 instead of zlib.output_compression="On" + * This is only needed if you want to configure a directory that only + consists of PHP scripts (same like a cgi-bin directory): + +<Object name="x-httpd-php"> +ObjectType fn="force-type" type="magnus-internal/x-httpd-php" +Service fn=php4_execute [inikey=value inikey=value ...] +</Object> + + After that you can configure a directory in the Administration + server and assign it the style x-httpd-php. All files in it will + get executed as PHP. This is nice to hide PHP usage by renaming + files to .html. + * Restart your web service and apply changes + * Do it for each web server instance you want PHP to run + + Note: More details about setting up PHP as an NSAPI filter can be + found here: http://benoit.noss.free.fr/php/install-php4.html + + Note: The stacksize that PHP uses depends on the configuration of + the webserver. If you get crashes with very large PHP scripts, it + is recommended to raise it with the Admin Server (in the section + "MAGNUS EDITOR"). + _________________________________________________________________ + +CGI environment and recommended modifications in php.ini + + Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE + WS/iPlanet/Netscape is a multithreaded web server. Because of that all + requests are running in the same process space (the space of the + webserver itself) and this space has only one environment. If you want + to get CGI variables like PATH_INFO, HTTP_HOST etc. it is not the + correct way to try this in the old PHP 3.x way with getenv() or a + similar way (register globals to environment, $_ENV). You would only + get the environment of the running webserver without any valid CGI + variables! + + Note: Why are there (invalid) CGI variables in the environment? + + Answer: This is because you started the webserver process from the + admin server which runs the startup script of the webserver, you + wanted to start, as a CGI script (a CGI script inside of the admin + server!). This is why the environment of the started webserver has + some CGI environment variables in it. You can test this by starting + the webserver not from the administration server. Use the command + line as root user and start it manually - you will see there are no + CGI-like environment variables. + + Simply change your scripts to get CGI variables in the correct way for + PHP 4.x by using the superglobal $_SERVER. If you have older scripts + which use $HTTP_HOST, etc., you should turn on register_globals in + php.ini and change the variable order too (important: remove "E" from + it, because you do not need the environment here): +variables_order = "GPCS" +register_globals = On + _________________________________________________________________ + +Special use for error pages or self-made directory listings (PHP >= 4.3.3) + + You can use PHP to generate the error pages for "404 Not Found" or + similar. Add the following line to the object in obj.conf for every + error page you want to overwrite: +Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value ini +key=value...] + + where XXX is the HTTP error code. Please delete any other Error + directives which could interfere with yours. If you want to place a + page for all errors that could exist, leave the code parameter out. + Your script can get the HTTP status code with $_SERVER['ERROR_TYPE']. + + Another possibility is to generate self-made directory listings. Just + create a PHP script which displays a directory listing and replace the + corresponding default Service line for + type="magnus-internal/directory" in obj.conf with the following: +Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/scr +ipt.php" [inikey=value inikey=value...] + + For both error and directory listing pages the original URI and + translated URI are in the variables $_SERVER['PATH_INFO'] and + $_SERVER['PATH_TRANSLATED']. + _________________________________________________________________ + +Note about nsapi_virtual() and subrequests (PHP >= 4.3.3) + + The NSAPI module now supports the nsapi_virtual() function (alias: + virtual()) to make subrequests on the webserver and insert the result + in the webpage. The problem is, that this function uses some + undocumented features from the NSAPI library. + + Under Unix this is not a problem, because the module automatically + looks for the needed functions and uses them if available. If not, + nsapi_virtual() is disabled. + + Under Windows limitations in the DLL handling need the use of a + automatic detection of the most recent ns-httpdXX.dll file. This is + tested for servers till version 6.1. If a newer version of the Sun + server is used, the detection fails and nsapi_virtual() is disabled. + + If this is the case, try the following: Add the following parameter to + php4_init in magnus.conf/obj.conf: + Init fn=php4_init ... server_lib="ns-httpdXX.dll" + + where XX is the correct DLL version number. To get it, look in the + server-root for the correct DLL name. The DLL with the biggest + filesize is the right one. + + You can check the status by using the phpinfo() function. + + Note: But be warned: Support for nsapi_virtual() is EXPERIMENTAL!!! + _________________________________________________________________ + +OmniHTTPd Server + + This section contains notes and hints specific to OmniHTTPd on + Windows. + + Note: You should read the manual installation steps first! + + Warning + + By using the CGI setup, your server is open to several possible + attacks. Please read our CGI security section to learn how to defend + yourself from those attacks. + + You need to complete the following steps to make PHP work with + OmniHTTPd. This is a CGI executable setup. SAPI is supported by + OmniHTTPd, but some tests have shown that it is not so stable to use + PHP as an ISAPI module. + + Important for CGI users: Read the faq on cgi.force_redirect for + important details. This directive needs to be set to 0. + + 1. Install OmniHTTPd server. + 2. Right click on the blue OmniHTTPd icon in the system tray and + select Properties + 3. Click on Web Server Global Settings + 4. On the 'External' tab, enter: virtual = .php | actual = + c:\php\php.exe (use php-cgi.exe if installing PHP 5), and use the + Add button. + 5. On the Mime tab, enter: virtual = wwwserver/stdcgi | actual = + .php, and use the Add button. + 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. + _________________________________________________________________ - Syntax error on line 1025 of c:/apache/apache/conf/httpd.conf: - Cannot load c:/php/php-4.2.1-win32/php5apache.dll into server +Sambar Server on Microsoft Windows - But c:/php/php-4.2.1-win32/php5apache.dll definitely - exists: + This section contains notes and hints specific to the Sambar Server + for Windows. - dir c:\php\php-4.2.1-win32\php5apache.dll - Directory of c:\php\php-4.2.1-win32 - 13.05.2002 00:01 24.576 php5apache.dll + Note: You should read the manual installation steps first! - 'strace'ing the apache.exe binary revealed the following: - c: - cd \apache\apache - strace apache >strace.txt + This list describes how to set up the ISAPI module to work with the + Sambar server on Windows. - Then looking into strace.txt: - [...] -729 3348 3248 NtOpenSection (0xe, {24, 24, 0x40, 0, 0, "php5ts.dll"}, ... ) == STATUS_OBJECT_NAME_NOT_FOUND -731 3348 3248 NtQueryAttributesFile ({24, 0, 0x40, 0, 0, "\??\c:\php\php-4.2.1-win32\php5ts.dll"}, 1234824, ... ) == STATUS_OBJECT_NAME_NOT_FOUND -733 3348 3248 NtQueryAttributesFile ({24, 108, 0x40, 0, 0, "php5ts.dll"}, 1234824, ... ) == STATUS_OBJECT_NAME_NOT_FOUND -735 3348 3248 NtQueryAttributesFile ({24, 0, 0x40, 0, 0, "\??\C:\WINNT\System32\php5ts.dll"}, 1234824, ... ) == STATUS_OBJECT_NAME_NOT_FOUND - [...] - - This went on quiet some time for all directories in the %PATH% - environment variable. The solution finally was to copy - php5ts.dll in any of the directories searched by the System (I - prefered to use c:\php\php-4.2.1-win32). - - Note: This does not only apply to php5ts.dll but in fact to every - DLL which gets loaded through PHP too. So, if you've - problems running your PHP CLI application because it - can't load a certain library but you're sure it's there, - try this tool. - - - I'm using IIS/CGI and everytime I try to access a php file I get - "Security Alert! The PHP CGI cannot be accessed directly." - - Since 4.1.2, the php.ini setting cgi.force_redirect defaults to '1' which - effectively prevents the cgi from working within IIS. You need to set up at - least a minimal php.ini file with the following directive: - - cgi.force_redirect = 0 - - If it doesn't work immidiately, make sure you have the php.ini file in the - right place (%SYSTEMROOT%\php.ini). - - - 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 + * Find the file called mappings.ini (in the config directory) in the + Sambar install directory. + * Open mappings.ini and add the following line under [ISAPI]: - 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. + Example 2-7. ISAPI configuration of Sambar +#for PHP 4 +*.php = c:\php\php4isapi.dll + +#for PHP 5 +*.php = c:\php\php5isapi.dll + + (This line assumes that PHP was installed in c:\php.) + * Now restart the Sambar server for the changes to take effect. + _________________________________________________________________ + +Xitami on Microsoft Windows + + This section contains notes and hints specific to Xitami on Windows. + + Note: You should read the manual installation steps first! + + This list describes how to set up the PHP CGI binary to work with + Xitami on Windows. + + Important for CGI users: Read the faq on cgi.force_redirect for + important details. This directive needs to be set to 0. If you want + to use $_SERVER['PHP_SELF'] you have to enable the cgi.fix_pathinfo + directive. + + Warning + + By using the CGI setup, your server is open to several possible + attacks. Please read our CGI security section to learn how to defend + yourself from those attacks. + + * 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 CGI + executable i.e. C:\php\php.exe for PHP 4, or C:\php\php-cgi.exe + for PHP 5. + * Press the 'Save' icon. + * Restart the server to reflect changes. + _________________________________________________________________ + +Installation of extensions on Windows + + After installing PHP and a webserver on Windows, you will probably + want to install some extensions for added functionality. You can + choose which extensions you would like to load when PHP starts by + modifying your php.ini. You can also load a module dynamically in your + script using dl(). + + The DLLs for PHP extensions are prefixed with php_. + + Note: In PHP 4.3.1 BCMath, Calendar, COM, Ctype, FTP, MySQL, ODBC, + Overload, PCRE, Session, Tokenizer, WDDX, XML and Zlib 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 or this table for a list of built in modules. + + The default location PHP searches for extensions is c:\php4\extensions + in PHP 4 and c:\php5 in PHP 5. To change this setting to reflect your + setup of PHP edit your php.ini file: + + * You will need to change the extension_dir setting to point to the + directory where your extensions lives, or where you have placed + your php_*.dll files. Please do not forget the last backslash. For + example: + +extension_dir = c:/php/extensions/ + + * Enable the extension(s) in php.ini you want to use by uncommenting + the extension=php_*.dll lines in php.ini. This is done by deleting + the leading ; form the extension you want to load. + + Example 2-8. Enable Bzip2 extension for PHP-Windows +// change the following line from ... +;extension=php_bz2.dll + +// ... to +extension=php_bz2.dll + + * Some of the extensions need extra DLLs to work. Couple of them can + be found in the distribution package, in the C:\php\dlls\ folder + in PHP 4 or in the main folder in PHP 5, but some, for example + Oracle (php_oci8.dll) require DLLs which are not bundled with the + distribution package. If you are installing PHP 4, copy the + bundled DLLs from C:\php\dlls folder to the main C:\php folder. + Don't forget to include C:\php in the system PATH (this process is + explained in a separate FAQ entry). + + Note: If you are running a server module version of PHP remember to + restart your webserver to reflect your changes to php.ini. + + The following table describes some of the extensions available and + required additional dlls. + + Table 2-1. PHP Extensions + Extension Description Notes + php_bz2.dll bzip2 compression functions None + php_calendar.dll Calendar conversion functions Built in since PHP + 4.0.3 + php_cpdf.dll ClibPDF functions None + php_crack.dll Crack functions None + php_ctype.dll ctype family functions Built in since PHP 4.3.0 + php_curl.dll CURL, Client URL library functions Requires: + libeay32.dll, ssleay32.dll (bundled) + php_cybercash.dll Cybercash payment functions PHP <= 4.2.0 + php_db.dll DBM functions Deprecated. Use DBA instead (php_dba.dll) + php_dba.dll DBA: DataBase (dbm-style) Abstraction layer functions None + php_dbase.dll dBase functions None + php_dbx.dll dbx functions + php_domxml.dll DOM XML functions PHP <= 4.2.0 requires: libxml2.dll + (bundled) PHP >= 4.3.0 requires: iconv.dll (bundled) + php_dotnet.dll .NET functions PHP <= 4.1.1 + php_exif.dll Read EXIF headers from JPEG None + php_fbsql.dll FrontBase functions PHP <= 4.2.0 + php_fdf.dll FDF: Forms Data Format functions. Requires: fdftk.dll + (bundled) + php_filepro.dll filePro functions Read-only access + php_ftp.dll FTP functions Built-in since PHP 4.0.3 + php_gd.dll GD library image functions Removed in PHP 4.3.2. Also note + that truecolor functions are not available in GD1, instead, use + php_gd2.dll. + php_gd2.dll GD library image functions GD2 + php_gettext.dll Gettext functions PHP <= 4.2.0 requires + gnu_gettext.dll (bundled), PHP >= 4.2.3 requires libintl-1.dll, + iconv.dll (bundled). + php_hyperwave.dll HyperWave functions None + php_iconv.dll ICONV characterset conversion Requires: iconv-1.3.dll + (bundled), PHP >=4.2.1 iconv.dll + php_ifx.dll Informix functions Requires: Informix libraries + php_iisfunc.dll IIS management functions None + php_imap.dll IMAP POP3 and NNTP functions None + php_ingres.dll Ingres II functions Requires: Ingres II libraries + php_interbase.dll InterBase functions Requires: gds32.dll (bundled) + php_java.dll Java functions PHP <= 4.0.6 requires: jvm.dll (bundled) + php_ldap.dll LDAP functions PHP <= 4.2.0 requires libsasl.dll + (bundled), PHP >= 4.3.0 requires libeay32.dll, ssleay32.dll (bundled) + php_mbstring.dll Multi-Byte String functions None + php_mcrypt.dll Mcrypt Encryption functions Requires: libmcrypt.dll + php_mhash.dll Mhash functions PHP >= 4.3.0 requires: libmhash.dll + (bundled) + php_mime_magic.dll Mimetype functions Requires: magic.mime (bundled) + php_ming.dll Ming functions for Flash None + php_msql.dll mSQL functions Requires: msql.dll (bundled) + php_mssql.dll MSSQL functions Requires: ntwdblib.dll (bundled) + php_mysql.dll MySQL functions PHP >= 5.0.0, requires libmysql.dll + (bundled) + php_mysqli.dll MySQLi functions PHP >= 5.0.0, requires libmysqli.dll + (bundled) + php_oci8.dll Oracle 8 functions Requires: Oracle 8.1+ client libraries + php_openssl.dll OpenSSL functions Requires: libeay32.dll (bundled) + php_oracle.dll Oracle functions Requires: Oracle 7 client libraries + php_overload.dll Object overloading functions Built in since PHP 4.3.0 + php_pdf.dll PDF functions None + php_pgsql.dll PostgreSQL functions None + php_printer.dll Printer functions None + php_shmop.dll Shared Memory functions None + php_snmp.dll SNMP get and walk functions NT only! + php_soap.dll SOAP functions PHP >= 5.0.0 + php_sockets.dll Socket functions None + php_sybase_ct.dll Sybase functions Requires: Sybase client libraries + php_tidy.dll Tidy functions PHP >= 5.0.0 + php_tokenizer.dll Tokenizer functions Built in since PHP 4.3.0 + php_w32api.dll W32api functions None + php_xmlrpc.dll XML-RPC functions PHP >= 4.2.1 requires: iconv.dll + (bundled) + php_xslt.dll XSLT functions PHP <= 4.2.0 requires sablot.dll, + expat.dll (bundled). PHP >= 4.2.1 requires sablot.dll, expat.dll, + iconv.dll (bundled). + php_yaz.dll YAZ functions Requires: yaz.dll (bundled) + php_zip.dll Zip File functions Read only access + php_zlib.dll ZLib compression functions Built in since PHP 4.3.0 + _________________________________________________________________ + +Chapter 3. Problems? + +Read the FAQ + + Some problems are more common than others. The most common ones are + listed in the PHP FAQ, part of this manual. + _________________________________________________________________ + +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 + http://www.php.net/support.php. 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 you are running PHP as + CGI or a server module, safe mode, etc...), and preferably enough code + to make others able to reproduce and test your 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. - - 1) Read about Bugs-Dos-And-Donts - http://bugs.php.net/bugs-dos-and-donts.php - - 2) If you think you've found a bug, read - http://bugs.php.net/bugs-dos-and-donts.php - 3) Feel welcome to file a report at - http://bugs.php.net/ + 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/. Please do not send bug + reports in mailing list or personal letters. The bug system is also + suitable to submit feature requests. + + Read the How to report a bug document before submitting any bug + reports! + _________________________________________________________________ + +Chapter 4. Runtime Configuration + +The configuration file + + The configuration file (called php3.ini in PHP 3, and simply php.ini + as of PHP 4) is read when PHP starts up. For the server module + versions of PHP, this happens only once when the web server is + started. For the CGI and CLI version, it happens on every invocation. + + The default location of php.ini is a compile time option (see the FAQ + entry), but can be changed for the CGI and CLI version with the -c + command line switch, see the chapter about using PHP from the command + line. You can also use the environment variable PHPRC for an + additional path to search for a php.ini file. + + If php-SAPI.ini exists (where SAPI is used SAPI, so the filename is + e.g. php-cli.ini or php-apache.ini), it's used instead of php.ini. + + Note: The Apache web server changes the directory to root at + startup causing PHP to attempt to read php.ini from the root + filesystem if it exists. + + The php.ini directives handled by extensions are documented + respectively on the pages of the extensions themselfs. The list of the + core directives is available in the appendix. Probably not all the PHP + directives are documented in the manual though. For a completel list + of directives available in your PHP version, please read your well + commented php.ini file. Alternatively, you may find the the latest + php.ini from CVS helpful too. + + Example 4-1. php.ini example +; any text on a line after an unquoted semicolon (;) is ignored +[php] ; section markers (text within square brackets) are also ignored +; Boolean values can be set to either: +; true, on, yes +; or false, off, no, none +register_globals = off +track_errors = yes + +; you can enclose strings in double-quotes +include_path = ".:/usr/local/lib/php" + +; backslashes are treated the same as any other character +include_path = ".;c:\php\lib" + _________________________________________________________________ + +How to change configuration settings + +Running PHP as an Apache module + + When using PHP as an Apache module, you can also change the + configuration settings using directives in Apache configuration files + (e.g. httpd.conf) and .htaccess files. You will need "AllowOverride + Options" or "AllowOverride All" privileges to do so. + + With PHP 4 and PHP 5, there are several Apache directives that allow + you to change the PHP configuration from within the Apache + configuration files. For a listing of which directives are + PHP_INI_ALL, PHP_INI_PERDIR, or PHP_INI_SYSTEM, have a look at the + table found within the ini_set() documentation. + + Note: With PHP 3, there are Apache directives that correspond to + each configuration setting in the php3.ini name, except the name is + prefixed by "php3_". + + php_value name value + Sets the value of the specified directive. Can be used only + with PHP_INI_ALL and PHP_INI_PERDIR type directives. To clear a + previously set value use none as the value. + + Note: Don't use php_value to set boolean values. php_flag (see + below) should be used instead. + + php_flag name on|off + Used to set a boolean configuration directive. Can be used only + with PHP_INI_ALL and PHP_INI_PERDIR type directives. + + php_admin_value name value + Sets the value of the specified directive. This can not be used + in .htaccess files. Any directive type set with php_admin_value + can not be overridden by .htaccess or virtualhost directives. + To clear a previously set value use none as the value. + + php_admin_flag name on|off + Used to set a boolean configuration directive. This can not be + used in .htaccess files. Any directive type set with + php_admin_flag can not be overridden by .htaccess or + virtualhost directives. + + Example 4-2. Apache configuration example +<IfModule mod_php5.c> + php_value include_path ".:/usr/local/lib/php" + php_admin_flag safe_mode on +</IfModule> +<IfModule mod_php4.c> + php_value include_path ".:/usr/local/lib/php" + php_admin_flag safe_mode on +</IfModule> +<IfModule mod_php3.c> + php3_include_path ".:/usr/local/lib/php" + php3_safe_mode on +</IfModule> + + Caution + + PHP constants do not exist outside of PHP. For example, in httpd.conf + you can not use PHP constants such as E_ALL or E_NOTICE to set the + error_reporting directive as they will have no meaning and will + evaluate to 0. Use the associated bitmask values instead. These + constants can be used in php.ini + _________________________________________________________________ + +Changing PHP configuration via the Windows registry + + When running PHP on Windows, the configuration values can be modified + on a per-directory basis using the Windows registry. The configuration + values are stored in the registry key HKLM\SOFTWARE\PHP\Per Directory + Values, in the sub-keys corresponding to the path names. For example, + configuration values for the directory c:\inetpub\wwwroot would be + stored in the key HKLM\SOFTWARE\PHP\Per Directory + Values\c\inetpub\wwwroot. The settings for the directory would be + active for any script running from this directory or any subdirectory + of it. The values under the key should have the name of the PHP + configuration directive and the string value. PHP constants in the + values are not parsed. + _________________________________________________________________ + +Other interfaces to PHP + + Regardless of how you run PHP, you can change certain values at + runtime of your scripts through ini_set(). See the documentation on + the ini_set() page for more information. + + If you are interested in a complete list of configuration settings on + your system with their current values, you can execute the phpinfo() + function, and review the resulting page. You can also access the + values of individual configuration directives at runtime using + ini_get() or get_cfg_var(). |