Quick Installation Instructions (Apache Module Version)

1.  gunzip apache_1.3.x.tar.gz
2.  tar xvf apache_1.3.x.tar
3.  gunzip php-x.x.x.tar.gz
4.  tar xvf php-x.x.x.tar
5.  cd apache_1.3.x
6.  ./configure --prefix=/www
7.  cd ../php-x.x.x
8.  ./configure --with-mysql --with-apache=../apache_1.3.x --enable-track-vars
9.  make
10. make install
11. cd ../apache_1.3.x
12. for PHP 3: ./configure --activate-module=src/modules/php3/libphp3.a
    for PHP 4: ./configure --activate-module=src/modules/php4/libphp4.a
13. make
14. make install

  Instead of this step you may prefer to simply copy the httpd binary
  overtop of your existing binary.  Make sure you shut down your
  server first though.

15. cd ../php-x.x.x
16. for PHP 3: cp php3.ini-dist /usr/local/lib/php3.ini
    for PHP 4: cp php.ini-dist /usr/local/lib/php.ini

  You can edit your .ini file to set PHP options.  If
  you prefer this file in another location, use
  --with-config-file-path=/path in step 8.

17. Edit your httpd.conf or srm.conf file and add: 
      
     For PHP 3:   AddType application/x-httpd-php3 .php3
     For PHP 4:   AddType application/x-httpd-php .php
 
  You can choose any extension you wish here.  .php is simply the one
  we suggest.

18. Use your normal procedure for starting the Apache server. (You must
    stop and restart the server, not just cause the server to reload by
    use a HUP or USR1 signal.)
      

Apache Module

PHP can be compiled in a number of different ways. Here is a quick summary:

./configure --with-apxs --with-pgsql
      

This will create a libphp4.so shared library that is loaded into Apache using a LoadModule line in Apache's httpd.conf file. The PostgreSQL support is embedded into this libphp4.so library.

./configure --with-apxs --with-pgsql=shared
      

This will again create a libphp4.so shared library for Apache, but it will also create a pgsql.so shared library that is loaded into PHP either by using the extension directive in php.ini file or by loading it explicitly in a script using the dl() function.

./configure --with-apache=/path/to/apache_source --with-pgsql
      

This will create a libmodphp4.a library, a mod_php4.c and some accompanying files and copy this into the src/modules/php4 directory in the Apache source tree. Then you compile Apache using --activate-module=src/modules/php4/libphp4.a and the Apache build system will create libphp4.a and link it statically into the httpd binary. The PostgreSQL support is included directly into this httpd binary, so the final result here is a single httpd binary that includes all of Apache and all of PHP.

./configure --with-apache=/path/to/apache_source --with-pgsql=shared
      

Same as before, except instead of including PostgreSQL support directly into the final httpd you will get a pgsql.so shared library that you can load into PHP from eihter the php.ini file or directly using dl().

fhttpd Module

To build PHP as an fhttpd module, answer "yes" to "Build as an fhttpd module?" (the --with-fhttpd=DIR option to configure) and specify the fhttpd source base directory. The default directory is /usr/local/src/fhttpd. If you are running fhttpd, building PHP as a module will give better performance, more control and remote execution capability.

CGI version

The default is to build PHP as a CGI program. If you are running a web server PHP has module support for, you should generally go for that solution for performance reasons. However, the CGI version enables Apache users to run different PHP-enabled pages under different user-ids. Please make sure you read through the Security chapter if you are going to run PHP as a CGI.

Database Support Options

PHP has native support for a number of databases (as well as ODBC):

      --with-adabas=DIR
     

      --with-dbase
     

      --with-filepro
     

      --with-ibm-db2=DIR
     

      --with-msql=DIR
     

      --with-mysql=DIR
     

      --with-iodbc=DIR
     

      --with-openlink=DIR
     

      --with-oracle=DIR
     

      --with-pgsql=DIR
     

      --with-solid=DIR
     

      --with-sybase=DIR
     

      --with-sybase-ct=DIR
     

      --with-velocis=DIR
     

      --with-custom-odbc=DIR
     

      --disable-unified-odbc
     

      --with-ldap=DIR
     

Other configure options

      --with-mcrypt
     

      --enable-sysvsem
     

      --enable-sysvshm
     

      --with-xml
     

      --enable-maintainer-mode
     

      --with-system-regex
     

      --with-config-file-path=DIR
     

      --with-exec-dir=DIR
     

      --enable-debug
     

      --enable-safe-mode
     

      --enable-track-vars
     

      --enable-magic-quotes
     

      --enable-debugger
     

      --enable-discard-path
     

      --enable-bcmath
     

      --enable-force-cgi-redirect
     

      --disable-short-tags
     

      --enable-url-includes
     

      --disable-syntax-hl
     

Building

When PHP is configured, you are ready to build the CGI executable or the PHP library. The command make should take care of this. If it fails and you can't figure out why, see the Problems section.

Testing

If you have built PHP as a CGI program, you may test your build by typing make test. It is always a good idea to test your build. This way you may catch a problem with PHP on your platform early instead of having to struggle with it later.

Benchmarking

If you have built PHP as a CGI program, you may benchmark your build by typing make bench. Note that if safe mode is on by default, the benchmark may not be able to finish if it takes longer then the 30 seconds allowed. This is because the set_time_limit() can not be used in safe mode. Use the max_execution_time configuration setting to control this time for your own scripts. make bench ignores the configuration file.

General Installation Steps

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.

• Copy the file, 'php.ini-dist' to your '%WINDOWS%' directory and rename it to 'php.ini'. Your '%WINDOWS%' directory is typically:

  c:\windows for Windows 95/98

  c:\winnt or c:\winnt40 for NT servers

• Edit your 'php.ini' file:

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

  • If you are using Omni Httpd, 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 modules you would like to load when PHP starts. You can uncomment the: 'extension=php_*.dll' lines to load these modules. Some modules require you to have additional libraries installed on your system for the module to work correctly. The PHP FAQ has more information on where to get supporting libraries. You can also load a module dynamically in your script using: dl("php_*.dll");

  • On PWS and IIS, you can set the browscap.ini to point to: 'c:\windows\system\inetsrv\browscap.ini' on Windows 95/98 and 'c:\winnt\system32\inetsrv\browscap.ini' on NT Server. Additional information on using the browscap functionality in PHP can be found at this mirror, select the "source" button to see it in action.

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

Windows 95/98/NT and PWS/IIS 3

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

• Repeat these steps for each extension you wish to associate with PHP scripts.

• 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.exe. ex: c:\php\php.exe -q %1. (don't forget the %1).

• Exit Regedit.

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 NT and IIS 4

To install PHP on an NT Server running IIS 4, follow these instructions:

• In Internet Service Manager (MMC), select the Web site or the starting point directory of an application.

• Open the directory's property sheets (by right clicking and selecting properties), and then click the Home Directory, Virtual Directory, or Directory tab.

• Click the Configuration button, and then click the App Mappings tab.

• Click Add, and in the Executable box, type: c:\path-to-php-dir\php.exe %s %s. You MUST have the %s %s on the end, PHP will not function properly if you fail to do this.

• In the Extension box, type the file name extension you want associated with PHP scripts. (You must repeat step 5 and 6 for each extension you want accociated with PHP scripts. (.php and .phtml are common.)

• 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.

Windows 9x/NT and Apache 1.3.x

You must edit your srm.conf or httpd.conf to configure Apache to work with the PHP CGI binary.

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

• ScriptAlias /php/ "c:/path-to-php-dir/"

• AddType application/x-httpd-php .php

• AddType application/x-httpd-php .phtml

• Action application/x-httpd-php "/php/php.exe"

To use the source code highlighting feature, simply create a PHP script file and stick this code in: <?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. (this is only one way of doing it). Note: On Win-Apache all back slashes in a path statement such as: "c:\directory\file.ext", must be converted to forward slashes.

Omni HTTPd 2.0b1 for Windows

This has got to be the easiest config there is:

• Step 1: Install Omni 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.exe

• Step 5: On the Mime tab, enter: virtual = wwwserver/stdcgi | actual = .php

• Step 6: Click OK

Repeat steps 2 - 6 for each extension you want to associate with PHP.

PHP Modules

Read the FAQ

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

Bug reports

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

Other problems

If you are still stuck, someone on the PHP 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/. To subscribe to the PHP mailing list, send an empty mail to php-general-subscribe@lists.php.net. The mailing list address is php-general@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, etc.), and preferably enough code to make others able to reproduce and test your problem.

General Configuration Directives

Mail Configuration Directives

Safe Mode Configuration Directives

Debugger Configuration Directives

Extension Loading Directives

MySQL Configuration Directives

mSQL Configuration Directives

Postgres Configuration Directives

Sybase Configuration Directives

Sybase-CT Configuration Directives

Informix Configuration Directives

BC Math Configuration Directives

Browser Capability Configuration Directives

Unified ODBC Configuration Directives

Possible attacks

Using PHP as a CGI binary is an option for setups that for some reason do not wish to integrate PHP as a module into server software (like Apache), or will use PHP with different kinds of CGI wrappers to create safe chroot and setuid environments for scripts. This setup usually involves installing executable PHP binary to the web server cgi-bin directory. CERT advisory CA-96.11 recommends against placing any interpreters into cgi-bin. Even if the PHP binary can be used as a standalone interpreter, PHP is designed to prevent the attacks this setup makes possible:

• Accessing system files: http://my.host/cgi-bin/php?/etc/passwd

  The query information in a url after the question mark (?) is passed as command line arguments to the interpreter by the CGI interface. Usually interpreters open and execute the file specified as the first argument on the command line.

  When invoked as a CGI binary, PHP refuses to interpret the command line arguments.

• Accessing any web document on server: http://my.host/cgi-bin/php/secret/doc.html

  The path information part of the url after the PHP binary name, /secret/doc.html is conventionally used to specify the name of the file to be opened and interpreted by the CGI program. Usually some web server configuration directives (Apache: Action) are used to redirect requests to documents like http://my.host/secret/script.php3 to the PHP interpreter. With this setup, the web server first checks the access permissions to the directory /secret, and after that creates the redirected request http://my.host/cgi-bin/php/secret/script.php3. Unfortunately, if the request is originally given in this form, no access checks are made by web server for file /secret/script.php3, but only for the /cgi-bin/php file. This way any user able to access /cgi-bin/php is able to access any protected document on the web server.

  In PHP, compile-time configuration option --enable-force-cgi-redirect and runtime configuration directives doc_root and user_dir can be used to prevent this attack, if the server document tree has any directories with access restrictions. See below for full the explanation of the different combinations.

Case 1: only public files served

If your server does not have any content that is not restricted by password or ip based access control, there is no need for these configuration options. If your web server does not allow you to do redirects, or the server does not have a way to communicate to the PHP binary that the request is a safely redirected request, you can specify the option --disable-force-cgi-redirect to the configure script. You still have to make sure your PHP scripts do not rely on one or another way of calling the script, neither by directly http://my.host/cgi-bin/php/dir/script.php3 nor by redirection http://my.host/dir/script.php3.

Redirection can be configured in Apache by using AddHandler and Action directives (see below).

Case 2: using --enable-force-cgi-redirect

This compile-time option prevents anyone from calling PHP directly with a url like http://my.host/cgi-bin/php/secretdir/script.php3. Instead, PHP will only parse in this mode if it has gone through a web server redirect rule.

Usually the redirection in the Apache configuration is done with the following directives:

Action php3-script /cgi-bin/php
AddHandler php3-script .php3
    

This option has only been tested with the Apache web server, and relies on Apache to set the non-standard CGI environment variable REDIRECT_STATUS on redirected requests. If your web server does not support any way of telling if the request is direct or redirected, you cannot use this option and you must use one of the other ways of running the CGI version documented here.

Case 3: setting doc_root or user_dir

To include active content, like scripts and executables, in the web server document directories is sometimes consider an insecure practice. If, because of some configuration mistake, the scripts are not executed but displayed as regular HTML documents, this may result in leakage of intellectual property or security information like passwords. Therefore many sysadmins will prefer setting up another directory structure for scripts that are accessible only through the PHP CGI, and therefore always interpreted and not displayed as such.

Also if the method for making sure the requests are not redirected, as described in the previous section, is not available, it is necessary to set up a script doc_root that is different from web document root.

You can set the PHP script document root by the configuration directive doc_root in the configuration file, or you can set the environment variable PHP_DOCUMENT_ROOT. If it is set, the CGI version of PHP will always construct the file name to open with this doc_root and the path information in the request, so you can be sure no script is executed outside this directory (except for user_dir below).

Another option usable here is user_dir. When user_dir is unset, only thing controlling the opened file name is doc_root. Opening an url like http://my.host/~user/doc.php3 does not result in opening a file under users home directory, but a file called ~user/doc.php3 under doc_root (yes, a directory name starting with a tilde [~]).

If user_dir is set to for example public_php, a request like http://my.host/~user/doc.php3 will open a file called doc.php3 under the directory named public_php under the home directory of the user. If the home of the user is /home/user, the file executed is /home/user/public_php/doc.php3.

user_dir expansion happens regardless of the doc_root setting, so you can control the document root and user directory access separately.

Case 4: PHP parser outside of web tree

A very secure option is to put the PHP parser binary somewhere outside of the web tree of files. In /usr/local/bin, for example. The only real downside to this option is that you will now have to put a line similar to:

#!/usr/local/bin/php
      

To get PHP to handle PATH_INFO and PATH_TRANSLATED information correctly with this setup, the php parser should be compiled with the --enable-discard-path configure option.