diff options
| -rw-r--r-- | INSTALL | 1639 | ||||
| -rw-r--r-- | NEWS | 1 | ||||
| -rw-r--r-- | win32/install.txt | 2088 |
3 files changed, 2644 insertions, 1084 deletions
@@ -1,422 +1,1341 @@ -Installation Instructions for PHP 5 ------------------------------------ -STOP! +Installing PHP + _________________________________________________________________ + + Table of Contents + 1. General Installation Considerations + 2. Installation on Mac OS X + + Using Packages + Compiling for OS X Server + Compiling for MacOS X Client + + 3. Installation on Unix systems + + Gentoo installation notes + HP-UX specific installation notes + OpenBSD installation notes + Solaris specific installation tips + Apache 1.3.x on Unix systems + Apache 2.0 on Unix systems + Caudium + fhttpd related notes + Sun, iPlanet and Netscape servers on Sun Solaris + CGI and commandline setups + + 4. Problems? + + Read the FAQ + Other problems + Bug reports + + 5. 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 Mac OS X + + This section contains notes and hints specific to installing PHP on + Mac OS X. There are two slightly different versions of Mac OS X, + Client and Server, our manual deals with installing PHP on both + systems. Note that PHP is not available for MacOS 9 and earlier + versions. + _________________________________________________________________ + +Using Packages + + There are a few pre-packaged and pre-compiled versions of PHP for Mac + OS X. This can help in setting up a standard configuration, but if you + need to have a different set of features (such as a secure server, or + a different database driver), you may need to build PHP and/or your + web server yourself. If you are unfamiliar with building and compiling + your own software, it's worth checking whether somebody has already + built a packaged version of PHP with the features you need. + _________________________________________________________________ + +Compiling for OS X Server + + Mac OS X Server install. + + 1. Get the latest distributions of Apache and PHP. + 2. Untar them, and run the configure program on Apache like so. + +./configure --exec-prefix=/usr \ +--localstatedir=/var \ +--mandir=/usr/share/man \ +--libexecdir=/System/Library/Apache/Modules \ +--iconsdir=/System/Library/Apache/Icons \ +--includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ +--enable-shared=max \ +--enable-module=most \ +--target=apache + + 3. If you want the compiler to do some optimization, you may also + want to add this line: + +setenv OPTIM=-O2 + + 4. Next, go to the PHP 4 source directory and configure it. + +./configure --prefix=/usr \ + --sysconfdir=/etc \ + --localstatedir=/var \ + --mandir=/usr/share/man \ + --with-xml \ + --with-apache=/src/apache_1.3.12 + + If you have any other additions (MySQL, GD, etc.), be sure to add + them here. For the --with-apache string, put in the path to your + apache source directory, for example /src/apache_1.3.12. + 5. Type make and make install. This will add a directory to your + Apache source directory under src/modules/php4. + 6. Now, reconfigure Apache to build in PHP 4. + +./configure --exec-prefix=/usr \ +--localstatedir=/var \ +--mandir=/usr/share/man \ +--libexecdir=/System/Library/Apache/Modules \ +--iconsdir=/System/Library/Apache/Icons \ +--includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ +--enable-shared=max \ +--enable-module=most \ +--target=apache \ +--activate-module=src/modules/php4/libphp4.a + + You may get a message telling you that libmodphp4.a is out of + date. If so, go to the src/modules/php4 directory inside your + Apache source directory and run this command: ranlib libmodphp4.a. + Then go back to the root of the Apache source directory and run + the above configure command again. That'll bring the link table up + to date. Run make and make install again. + 7. Copy and rename the php.ini-dist file to your bin directory from + your PHP 4 source directory: cp php.ini-dist + /usr/local/bin/php.ini or (if your don't have a local directory) + cp php.ini-dist /usr/bin/php.ini. + _________________________________________________________________ + +Compiling for MacOS X Client + + The following instructions will help you install a PHP module for the + Apache web server included in MacOS X. This version includes support + for the MySQL and PostgreSQL databases. These instructions are + graciously provided by Marc Liyanage. + + Warning + + Be careful when you do this, you could screw up your Apache web + server! + + Do this to install: + + 1. Open a terminal window. + 2. Type wget + http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz, + wait for the download to finish. + 3. Type gunzip libphp4.so.gz. + 4. Type sudo apxs -i -a -n php4 libphp4.so + 5. Now type sudo open -a TextEdit /etc/httpd/httpd.conf. TextEdit + will open with the web server configuration file. Locate these two + lines towards the end of the file: (Use the Find command) + +#AddType application/x-httpd-php .php +#AddType application/x-httpd-php-source .phps + + Remove the two hash marks (#), then save the file and quit + TextEdit. + 6. Finally, type sudo apachectl graceful to restart the web server. + + PHP should now be up and running. You can test it by dropping a file + into your Sites folder which is called test.php. Into that file, write + this line: <?php phpinfo() ?>. + + Now open up 127.0.0.1/~your_username/test.php in your web browser. You + should see a status table with information about the PHP module. + _________________________________________________________________ + +Chapter 3. Installation on Unix systems + + This section will guide you through the general configuration and + installation of PHP on Unix systems. Be sure to investigate any + sections specific to your platform or web server before you begin the + process. + + As our manual outlines in the General Installation Considerations + section, we are mainly dealing with web centric setups of PHP in this + section, although we will cover setting up PHP for command line usage + as well. + + There are several ways to install PHP for the Unix platform, either + with a compile and configure process, or through various pre-packaged + methods. This documentation is mainly focused around the process of + compiling and configuring PHP. Many Unix like systems have some sort + of package installation system. This can assist in setting up a + standard configuration, but if you need to have a different set of + features (such as a secure server, or a different database driver), + you may need to build PHP and/or your webserver. If you are unfamiliar + with building and compiling your own software, it is worth checking to + see whether somebody has already built a packaged version of PHP with + the features you need. + + Prerequisite knowledge and software for compiling: + + * Basic Unix skills (being able to operate "make" and a C compiler) + * An ANSI C compiler + * flex + * bison + * A web server + * Any module specific components (such as gd, pdf libs, etc.) + + The initial PHP setup and configuration process is controlled by the + use of the commandline options of the configure script. Our manual + documents the different options separately. You will find the core + options in the appendix, while the different extension specific + options are descibed on the reference pages. + + When PHP is configured, you are ready to build the module and/or + executables. The command make should take care of this. If it fails + and you can't figure out why, see the Problems section. + _________________________________________________________________ + +Gentoo installation notes + + This section contains notes and hints specific to installing PHP on + Gentoo Linux. + _________________________________________________________________ + +Using Portage (emerge) + + While you can just download the PHP source and compile it youself, + using Gentoo's packaging system is the simplest and cleanest method of + installing PHP. If you are not familiar with building software on + Linux, this is the way to go. + + If you have built your Gentoo system so far, you are probably used to + Portage already. Installing Apache and PHP is no different than the + other system tools. + + The first decision you need to make is whether you want to install + Apache 1.3.x or Apache 2.x. While both can be used with PHP, the steps + given bellow will use Apache 1.3.x. Another thing to consider is + whether your local Portage tree is up to date. If you have not updated + it recently, you need to run emerge sync before anything else. This + way, you will be using the most recent stable version of Apache and + PHP. + + Now that everything is in place, you can use the following example to + install Apache and PHP: + + Example 3-1. Gentoo Install Example with Apache 1.3 +# emerge \<apache-2 +# USE="-*" emerge php mod_php +# ebuild /var/db/pkg/dev-php/mod_php-<your PHP version>/mod_php-<your PHP versi +on>.ebuild config +# nano /etc/conf.d/apache + Add "-D PHP4" to APACHE_OPTS + +# rc-update add apache default +# /etc/init.d/apache start + + You can read more about emerge in the excellent Portage Manual + provided on the Gentoo website. + + If you need to use Apache 2, you can simply use emerge apache in the + last example. + _________________________________________________________________ + +Better control on configuration + + In the last section, PHP was emerged without any activated modules. As + of this writing, the only module activated by default with Portage is + XML which is needed by PEAR. This may not be what you want and you + will soon discover that you need more activated modules, like MySQL, + gettext, GD, etc. + + When you compile PHP from source yourself, you need to activate + modules via the configure command. With Gentoo, you can simply provide + USE flags which will be passed to the configure script automatically. + To see which USE flags to use with emerge, you can try: + + Example 3-2. Getting the list of valid USE flags +# USE="-*" emerge -pv php + +[ebuild N ] dev-php/php-4.3.6-r1 -X -berkdb -crypt -curl -debug -doc +-fdftk -firebird -flash -freetds -gd -gd-external -gdbm -gmp -hardenedphp +-imap -informix -ipv6 -java -jpeg -kerberos -ldap -mcal -memlimit -mssql +-mysql -ncurses -nls -oci8 -odbc -pam -pdflib -png -postgres -qt -readline +-snmp -spell -ssl -tiff -truetype -xml2 -yaz 3,876 kB + + As you can see from the last output, PHP considers a lot of USE flags. + Look at them closely and choose what you need. If you choose a flag + and you do not have the proper librairies, Portage will compile them + for you. It is a good idea to use emerge -pv again to see what Portage + will compile in accordance to your USE flags. As an example, if you do + not have X installed and you choose to include X in the USE flags, + Portage will compile X prior to PHP, which can take a couple of hours. + + If you choose to compile PHP with MySQL, cURL and GD support, the + command will look something like this: + + Example 3-3. Install PHP with USE flags + # USE="-* curl mysql gd" emerge php mod_php + + As in the last example, do not forget to emerge php as well as + mod_php. php is responsible for the command line version of PHP as + mod_php is for the Apache module version of PHP. + _________________________________________________________________ + +Common Problems + + * If you see the PHP source instead of the result the script should + produce, you have probably forgot to edit /etc/conf.d/apache. + Apache needs to be started with the -D PHP4 flag. To see if the + flag is present, you should be able to see it when using ps ax | + grep apache while Apache is running. + * Due to slotting problems, you might end up with more than one + version of PHP installed on your system. If this is the case, you + need to unmerge the old versions manually by using emerge unmerge + mod_php-<old version>. + * If you cannot emerge PHP because of Java, try putting -* in front + of your USE flags like in the above examples. + * If you are having problems configuring Apache and PHP, you can + always search the Gentoo Forums. Try searching with the keywords + "Apache PHP". + _________________________________________________________________ + +HP-UX specific installation notes + + This section contains notes and hints specific to installing PHP on + HP-UX systems. (Contributed by paul_mckay at clearwater-it dot co dot + uk). + + Note: These tips were written for PHP 4.0.4 and Apache 1.3.9. + + 1. You need gzip, download a binary distribution from + http://hpux.connect.org.uk/ftp/hpux/Gnu/gzip-1.2.4a/gzip-1.2.4a-sd + -10.20.depot.Z uncompress the file and install using swinstall. + 2. You need gcc, download a binary distribution from + http://gatekeep.cs.utah.edu/ftp/hpux/Gnu/gcc-2.95.2/gcc-2.95.2-sd- + 10.20.depot.gz. uncompress this file and install gcc using + swinstall. + 3. You need the GNU binutils, you can download a binary distribution + from + http://hpux.connect.org.uk/ftp/hpux/Gnu/binutils-2.9.1/binutils-2. + 9.1-sd-10.20.depot.gz. uncompress this file and install binutils + using swinstall. + 4. You now need bison, you can download a binary distribution from + http://hpux.connect.org.uk/ftp/hpux/Gnu/bison-1.28/bison-1.28-sd-1 + 0.20.depot.gz, install as above. + 5. You now need flex, you need to download the source from one of the + http://www.gnu.org mirrors. It is in the non-gnu directory of the + ftp site. Download the file, gunzip, then tar -xvf it. Go into the + newly created flex directory and run ./configure, followed by + make, and then make install. + If you have errors here, it's probably because gcc etc. are not in + your PATH so add them to your PATH. + 6. Download the PHP and apache sources. + 7. gunzip and tar -xvf them. We need to hack a couple of files so + that they can compile OK. + 8. Firstly the configure file needs to be hacked because it seems to + lose track of the fact that you are a hpux machine, there will be + a better way of doing this but a cheap and cheerful hack is to put + lt_target=hpux10.20 on line 47286 of the configure script. + 9. Next, the Apache GuessOS file needs to be hacked. Under + apache_1.3.9/src/helpers change line 89 from echo + "hp${HPUXMACH}-hpux${HPUXVER}"; exit 0 to: echo + "hp${HPUXMACH}-hp-hpux${HPUXVER}"; exit 0 + 10. You cannot install PHP as a shared object under HP-UX so you must + compile it as a static, just follow the instructions at the Apache + page. + 11. PHP and Apache should have compiled OK, but Apache won't start. + you need to create a new user for Apache, e.g. www, or apache. You + then change lines 252 and 253 of the conf/httpd.conf in Apache so + that instead of + +User nobody +Group nogroup + + you have something like + +User www +Group sys + + This is because you can't run Apache as nobody under hp-ux. Apache + and PHP should then work. + _________________________________________________________________ + +OpenBSD installation notes + + This section contains notes and hints specific to installing PHP on + OpenBSD 3.4. + _________________________________________________________________ + +Using Binary Packages + + Using binary packages to install PHP on OpenBSD is the recommended and + simplest method. The core package has been separated from the various + modules, and each can be installed and removed independently from the + others. The files you need can be found on your OpenBSD CD or on the + FTP site. + + The main package you need to install is php4-core-4.3.3.tgz, which + contains the basic engine (plus gettext and iconv). Next, take a look + at the module packages, such as php4-mysql-4.3.3.tgz or + php4-imap-4.3.3.tgz. You need to use the phpxs command to activate and + deactivate these modules in your php.ini. + + Example 3-4. OpenBSD Package Install Example +# pkg_add php4-core-4.3.3.tgz +# /usr/local/sbin/phpxs -s +# cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini + (add in mysql) +# pkg_add php4-mysql-4.3.3.tgz +# /usr/local/sbin/phpxs -a mysql + (add in imap) +# pkg_add php4-imap-4.3.3.tgz +# /usr/local/sbin/phpxs -a imap + (remove mysql as a test) +# pkg_delete php4-mysql-4.3.3 +# /usr/local/sbin/phpxs -r mysql + (install the PEAR libraries) +# pkg_add php4-pear-4.3.3.tgz + + Read the packages(7) manual page for more information about binary + packages on OpenBSD. + _________________________________________________________________ + +Using Ports + + You can also compile up PHP from source using the ports tree. However, + this is only recommended for users familiar with OpenBSD. The PHP 4 + port is split into two sub-directories: core and extensions. The + extensions directory generates sub-packages for all of the supported + PHP modules. If you find you do not want to create some of these + modules, use the no_* FLAVOR. For example, to skip building the imap + module, set the FLAVOR to no_imap. + _________________________________________________________________ + +Common Problems + + * The default install of Apache runs inside a chroot(2) jail, which + will restrict PHP scripts to accessing files under /var/www. You + will therefore need to create a /var/www/tmp directory for PHP + session files to be stored, or use an alternative session backend. + In addition, database sockets need to be placed inside the jail or + listen on the localhost interface. If you use network functions, + some files from /etc such as /etc/resolv.conf and /etc/services + will need to be moved into /var/www/etc. The OpenBSD PEAR package + automatically installs into the correct chroot directories, so no + special modification is needed there. More information on the + OpenBSD Apache is available in the OpenBSD FAQ. + * The OpenBSD 3.4 package for the gd extension requires XFree86 to + be installed. If you do not wish to use some of the font features + that require X11, install the php4-gd-4.3.3-no_x11.tgz package + instead. + _________________________________________________________________ + +Older Releases + + Older releases of OpenBSD used the FLAVORS system to compile up a + statically linked PHP. Since it is hard to generate binary packages + using this method, it is now deprecated. You can still use the old + stable ports trees if you wish, but they are unsupported by the + OpenBSD team. If you have any comments about this, the current + maintainer for the port is Anil Madhavapeddy (avsm at openbsd dot + org). + _________________________________________________________________ + +Solaris specific installation tips + + This section contains notes and hints specific to installing PHP on + Solaris systems. + _________________________________________________________________ + +Required software + + Solaris installs often lack C compilers and their related tools. Read + this FAQ for information on why using GNU versions for some of these + tools is necessary. The required software is as follows: + + * gcc (recommended, other C compilers may work) + * make + * flex + * bison + * m4 + * autoconf + * automake + * perl + * gzip + * tar + * GNU sed + + In addition, you will need to install (and possibly compile) any + additional software specific to your configuration, such as Oracle or + MySQL. + _________________________________________________________________ + +Using Packages + + You can simplify the Solaris install process by using pkgadd to + install most of your needed components. + _________________________________________________________________ + +Apache 1.3.x on Unix systems + + This section contains notes and hints specific to Apache installs of + PHP on Unix platforms. We also have instructions and notes for Apache + 2 on a separate page. + + You can select arguments to add to the configure on line 10 below from + the list of core configure options and from extension specific options + described at the respective places in the manual. The version numbers + have been omitted here, to ensure the instructions are not incorrect. + You will need to replace the 'xxx' here with the correct values from + your files. + + Example 3-5. Installation Instructions (Apache Shared Module Version) + for PHP +1. gunzip apache_xxx.tar.gz +2. tar -xvf apache_xxx.tar +3. gunzip php-xxx.tar.gz +4. tar -xvf php-xxx.tar +5. cd apache_xxx +6. ./configure --prefix=/www --enable-module=so +7. make +8. make install +9. cd ../php-xxx + +10. Now, configure your PHP. This is where you customize your PHP + with various options, like which extensions will be enabled. Do a + ./configure --help for a list of available options. In our example + we'll do a simple configure with Apache 1 and MySQL support. Your + path to apxs may differ from our example. + + ./configure --with-mysql --with-apxs=/www/bin/apxs + +11. make +12. make install + + If you decide to change your configure options after installation, + you only need to repeat the last three steps. You only need to + restart apache for the new module to take effect. A recompile of + Apache is not needed. + + Note that unless told otherwise, 'make install' will also install PEAR, + various PHP tools such as phpize, install the PHP CLI, and more. + +13. Setup your php.ini file: + + cp php.ini-dist /usr/local/lib/php.ini + + You may edit your .ini file to set PHP options. If you prefer your + php.ini in another location, use --with-config-file-path=/some/path in + step 10. -Before going any further, please remember you are going to find more -up to date instructions in the online manual, located here: + If you instead choose php.ini-recommended, be certain to read the list + of changes within, as they affect how PHP behaves. + +14. Edit your httpd.conf to load the PHP module. The path on the right hand + side of the LoadModule statement must point to the path of the PHP + module on your system. The make install from above may have already + added this for you, but be sure to check. -http://www.php.net/manual/en/install.apache.php + For PHP 4: -For Apache 2, instructions and up-to-date information regarding its -support status, is available here: + LoadModule php4_module libexec/libphp4.so -http://www.php.net/manual/en/install.apache2.php + For PHP 5: -It is strongly recommended that you read the manual page before going -further. However, for the impatient, here is a quick set of steps that -will build PHP as (first) a dynamic Apache module (DSO) for Apache 1.3.x -with MySQL support and then a static module. A more verbose explanation follows. - -For installing PHP on other web servers, refer to one of the following -files: - - sapi/aolserver/README - sapi/pi3web/README - sapi/servlet/README - sapi/thttpd/README - README.Zeus - -Some notes: - -1: Only install either the static module or the dynamic one. Do not - install both. - -2: If you are recompiling PHP to add new extensions or upgrading - something like GD, remove the config.cache file before you re-run - configure. - -3: If you are on Linux and have installed shared libraries, make - sure the location of these shared libraries are listed in your - /etc/ld.so.conf file. For example, if you have: - - /usr/local/lib/mysql/libmysqlclient.so - - Make sure /etc/ld.so.conf contains: - - /usr/local/lib/mysql - - Then run ldconfig. - -If you want both PHP 3 and 4 modules in the same Apache server, check the -bottom of this file for instructions. - -INSTALLATION WITH THE ZEUS WEB SERVER: ---Please see the 'README.Zeus' file included in this distribution - - -QUICK INSTALL (DSO) - -For this to work your Apache httpd must have mod_so enabled. -Check using httpd -l. You should see something like: - -Compiled-in modules: - http_core.c - mod_so.c - -Chances are you will see a lot more modules than these two. That's ok, -as long as mod_so.c shows up you can proceed with the following steps: - -$ gunzip -c php-4.x.y.tar.gz | tar xf - -$ cd php-4.x.y -$ ./configure --with-mysql --with-apxs -$ make -$ make install - -If you get an error telling you that the apxs script could not be found, -look for it on your system and if you find it, provide the full path to it -as: --with-apxs=/path/to/apxs - -Make sure you specify the version of apxs that is actually installed on -your system and NOT the one that is in the apache source tarball. - -Next you must copy php.ini-dist to the appropriate place (normally -/usr/local/lib/php.ini) and edit it as necessary to set PHP options. - -The only thing left to do is to edit your httpd.conf file and make sure the -PHP 4 mime type is there and uncommented. You need a line that looks like -this: - - AddType application/x-httpd-php .php - -Then restart your server (apachectl restart) and you should be able to -serve up PHP files now. Make a test file called test.php and put some -PHP tags in it. Like <?phpinfo()?>, for example. - - -QUICK INSTALL (Static) - -$ gunzip -c apache_1.3.x.tar.gz | tar xf - -$ cd apache_1.3.x -$ ./configure -$ cd .. - -$ gunzip -c php-4.x.y.tar.gz | tar xf - -$ cd php-4.x.y -$ ./configure --with-mysql --with-apache=../apache_1.3.x -$ make -$ make install - -$ cd ../apache_1.3.x -$ ./configure --prefix=/www --activate-module=src/modules/php5/libphp5.a - (The above line is correct! Yes, we know libphp5.a does not exist at this - stage. It isn't supposed to. It will be created.) -$ make - (you should now have an httpd binary which you can copy to your Apache bin dir if - is is your first install then you need to "make install" as well) -$ cd ../php-4.x.y -$ cp php.ini-dist /usr/local/lib/php.ini -You can edit /usr/local/lib/php.ini file to set PHP options. -Edit your httpd.conf or srm.conf file and add: - AddType application/x-httpd-php .php - - -VERBOSE INSTALL - -Chances are you are reading this because the quick install steps above -did not work for you. If this is the case, congratulations, you are -among the elite few that actually reads documentation. It really is -not a difficult install and once you have done it once you will fly -through it. + LoadModule php5_module libexec/libphp5.so -Installing PHP can be done in four simple steps: +15. And in the AddModule section of httpd.conf, somewhere under the + ClearModuleList, add this: -1. Unpack your distribution file. + For PHP 4: - You will have downloaded a file named something like php-4.x.y.tar.gz. - Unzip this file with a command like: gunzip php-4.x.y.tar.gz + AddModule mod_php4.c - Next you have to untar it with: tar -xvf php-4.x.y.tar + For PHP 5: - This will create a php-4.x.y directory. cd into this new directory. + AddModule mod_php5.c -2a. Configure PHP (Dynamic Module) - Skip to 2b if you wish to build - a static module +16. Tell Apache to parse certain extensions as PHP. For example, + let's have Apache parse the .php extension as PHP. You could + have any extension(s) parse as PHP by simply adding more, with + each separated by a space. We'll add .phtml to demonstrate. - You now have to choose the options you would like. There are quite - a few of them. To see a list, type: ./configure --help + AddType application/x-httpd-php .php .phtml - The only options that you are likely to want to use are the ones in - the last section entitled, "--enable and --with options recognized:" + It's also common to setup the .phps extension to show highlighted PHP + source, this can be done with: - A popular choice is to build the Apache module version. In order to - build PHP as a dynamic module for Apache-1.3.x you have to first have - Apache installed. Assuming Apache is already installed, make sure - the shared object module is enabled. To check this, type: httpd -l - You should see something like: + AddType application/x-httpd-php-source .phps - Compiled-in modules: - http_core.c - mod_so.c +17. Use your normal procedure for starting the Apache server. (You must + stop and restart the server, not just cause the server to reload by + using a HUP or USR1 signal.) - You will most likely have a lot more modules than what is shown here. - As long as mod_so.c shows up in the list, PHP should be happy. + Depending on your Apache install and Unix variant, there are many + possible ways to stop and restart the server. Below are some typical + lines used in restarting the server, for different apache/unix + installations. You should replace /path/to/ with the path to these + applications on your systems. - Now, type: ./configure --with-mysql --with-apxs + Example 3-6. Example commands for restarting Apache +1. Several Linux and SysV variants: +/etc/rc.d/init.d/httpd restart - If you get an error telling you that the apxs script could not be found, - look for it on your system and if you find it, provide the full path to it - as: --with-apxs=/path/to/apxs +2. Using apachectl scripts: +/path/to/apachectl stop +/path/to/apachectl start - Make sure you specify the version of apxs that is actually installed on - your system and NOT the one that is in the apache source tarball. - - You might also want other flags on this configure line. --with-mysql - is just an example. +3. httpdctl and httpsdctl (Using OpenSSL), similar to apachectl: +/path/to/httpsdctl stop +/path/to/httpsdctl start - There are a few things that can go wrong during this configure step. - The most common is that you have asked for an option and that the - configure script can not find the files required to enable this - option in PHP. Chances are you can provide the full path to the - base directory under which the related files were installed. For - example, if you have installed the GD library in /opt/gd which means - that /opt/gd/include has your GD header files and /opt/gd/lib contains - your GD library files, you would use --with-gd=/opt/gd +4. Using mod_ssl, or another SSL server, you may want to manually +stop and start: +/path/to/apachectl stop +/path/to/apachectl startssl - Skip to step 3 for compilation and installation instructions. + The locations of the apachectl and http(s)dctl binaries often vary. If + your system has locate or whereis or which commands, these can assist + you in finding your server control programs. -2b. Configure PHP (Static Module) - Skip if you performed 2a + Different examples of compiling PHP for apache are as follows: - You now have to choose the options you would like. There are quite - a few of them. To see a list, type: ./configure --help + ./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 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 either the php.ini file or directly + using dl(). + + When choosing to build PHP in different ways, you should consider the + advantages and drawbacks of each method. Building as a shared object + will mean that you can compile apache separately, and don't have to + recompile everything as you add to, or change, PHP. Building PHP into + apache (static method) means that PHP will load and run faster. For + more information, see the Apache webpage on DSO support. + + Note: Apache's default httpd.conf currently ships with a section + that looks like this: - The only options that you are likely to want to use are the ones in - the last section entitled, "--enable and --with options recognized:" +User nobody +Group "#-1" - A popular choice is to build the Apache module version. You need - to know where the source code directory for your Apache server is - located. Then use an option like: --with-apache=/usr/local/src/apache - if that is your Apache source code directory. If you only specify - --with-apache, then it will default to look for your Apache source - in /usr/local/etc/httpd. + Unless you change that to "Group nogroup" or something like that + ("Group daemon" is also very common) PHP will not be able to open + files. - NOTE: The directory you specify should be the top-level of the - unpacked Apache (or Stronghold) distribution. The configure program - will automatically look for httpd.h in different directories under that - location depending on which version of Apache, including Stronghold, - you are running. + Note: Make sure you specify the installed version of apxs when + using --with-apxs=/path/to/apxs. You must NOT use the apxs version + that is in the apache sources but the one that is actually + installed on your system. + _________________________________________________________________ - For MySQL support, since newer versions of MySQL installs its various - components under /usr/local, this is the default. If you have - changed the location you can specify it with: --with-mysql=/opt/local - for example. Otherwise just use: --with-mysql +Apache 2.0 on Unix systems - *NOTE* If you are using Apache 1.3b6 or later, you should run the - Apache Configure script at least once before compiling PHP. It - doesn't matter how you have Apache configured at this point. + This section contains notes and hints specific to Apache 2.0 installs + of PHP on Unix systems. - Skip to step 3b at this point. + Warning -3. Compile and install the files. Simply type: make install + 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 -3a. Dynamic Module Installation + You are highly encouraged to take a look at the Apache Documentation + to get a basic understanding of the Apache 2.0 Server. - Nothing else is needed here. Proceed to step 4a. + 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: -3b. Static Module Installation + * 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. - For the Apache module version this will copy the appropriate files - to the src/modules/php5 directory in your Apache distribution if - you are using Apache 1.3.x. If you are still running Apache 1.2.x - these files will be copied directly to the main src directory. + These versions of PHP are compatible to Apache 2.0.40 and later. - For Apache 1.3b6 and later, you can use the new APACI configuration - mechanism. To automatically build Apache with PHP support, use: + 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. - cd apache_1.3.x - ./configure --prefix=/<path>/apache \ - --activate-module=src/modules/php5/libphp5.a - make - make install + All mentioned versions of PHP will work still with Apache 1.3.x. - If you do not wish to use this new configuration tool, the old - install procedure (src/Configure) will work fine. + Download the most recent version of Apache 2.0 and a fitting PHP + version from the above mentioned places. This quick guide covers only + the basics to get started with Apache 2.0 and PHP. For more + information read the Apache Documentation. The version numbers have + been omitted here, to ensure the instructions are not incorrect. You + will need to replace the 'NN' here with the correct values from your + files. - If you are using the old Apache ./Configure script, you will have to - edit the Apache src/Configuration file manually. If you do not have - this file, copy Configuration.tmpl to Configuration. + Example 3-7. Installation Instructions (Apache 2 Shared Module + Version) +1. gzip -d httpd-2_0_NN.tar.gz +2. tar xvf httpd-2_0_NN.tar +3. gunzip php-NN.tar.gz +4. tar -xvf php-NN.tar +5. cd httpd-2_0_NN +6. ./configure --enable-so +7. make +8. make install - For Apache 1.3.x add: + Now you have Apache 2.0.NN available under /usr/local/apache2, + configured with loadable module support and the standard MPM prefork. + To test the installation use your normal procedure for starting + the Apache server, e.g.: + /usr/local/apache2/bin/apachectl start + and stop the server to go on with the configuration for PHP: + /usr/local/apache2/bin/apachectl stop. - AddModule modules/php5/libphp5.a +9. cd ../php-NN - For Apache 1.3.x don't do anything else. Just add this line and then - run "./Configure" followed by "make". +10. Now, configure your PHP. This is where you customize your PHP + with various options, like which extensions will be enabled. Do a + ./configure --help for a list of available options. In our example + we'll do a simple configure with Apache 2 and MySQL support. Your + path to apxs may differ, in fact, the binary may even be named apxs2 on + your system. - For Apache 1.2.x add: + ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql - Module php5_module mod_php5.o +11. make +12. make install - For Apache 1.2.x you will also have to look in the libphp5.module file, - which was copied to the src directory. The EXTRA_LIBS line in the Apache - Configuration file needs to be set to use the same libs as specified on - the LIBS line in libphp5.module. You also need to make sure to add - "-L." to the beginning of the EXTRA_LIBS line. + If you decide to change your configure options after installation, + you only need to repeat the last three steps. You only need to + restart apache for the new module to take effect. A recompile of + Apache is not needed. - So, as an example, your EXTRA_LIBS line might look like: + Note that unless told otherwise, 'make install' will also install PEAR, + various PHP tools such as phpize, install the PHP CLI, and more. - EXTRA_LIBS=-L. -lphp5 -lgdbm -ldb -L/usr/local/mysql/lib -lmysqlclient +13. Setup your php.ini - NOTE: You should not enclose the EXTRA_LIBS line in double-quotes, as it - is in the libphp5.module file. + cp php.ini-dist /usr/local/lib/php.ini - Also, look at the RULE_WANTHSREGEX setting in the libphp5.module file - and set the WANTHSREGEX directive accordingly in your Configuration file. - This last step applies to versions of Apache prior to 1.3b3. + You may edit your .ini file to set PHP options. If you prefer having + php.ini in another location, use --with-config-file-path=/some/path in + step 10. - This is a bit of a hassle, but should serve as incentive to move to - Apache 1.3.x where this step has been eliminated. + If you instead choose php.ini-recommended, be certain to read the list + of changes within, as they affect how PHP behaves. - Once you are satisfied with your Configuration settings, type: ./Configure - If you get errors, chances are that you forgot a library or made a typo - somewhere. Re-edit Configuration and try again. If it goes well, - type: make +14. Edit your httpd.conf to load the PHP module. The path on the right hand + side of the LoadModule statement must point to the path of the PHP + module on your system. The make install from above may have already + added this for you, but be sure to check. - Assuming it compiles without errors, proceed to step 4b. + For PHP 4: -4a. Setting up the server. (Dynamic Module) + LoadModule php4_module libexec/libphp4.so - The make install command in step 3 should have done most of your - work for you. It actually edits your httpd.conf file and tries to - enable the dynamic PHP module. To verify this, look for a line that - looks like this: + For PHP 5: LoadModule php5_module libexec/libphp5.so - The actual path before the libphp5.so part might differ slightly. This - is likely fine. If you are paranoid you can examine the output from the - make install step to see where the libphp5.so file was actually put and - place the full path to this file on this LoadModule line. - - If somewhere in your httpd.conf file you have a ClearModuleList line - then you also need this line: +15. Tell Apache to parse certain extensions as PHP. For example, + let's have Apache parse the .php extension as PHP. You could + have any extension(s) parse as PHP by simply adding more, with + each separated by a space. We'll add .phtml to demonstrate. - AddModule mod_php5.c - - And finally you need to tell Apache which file extension should trigger - PHP. You do this by creating a special mime type and associating it - with an extension. We suggest using: - - AddType application/x-httpd-php .php - - You are however free to use any extension you wish, including .html. - - Note! If a line has a # at the beginning, then it is commented out - and you need to remove the # for that line to take effect. - - Finally you need to copy php.ini-dist to the appropriate place - (normally /usr/local/lib/php.ini) and edit if necessary. + AddType application/x-httpd-php .php .phtml - Once you have made these changes you should be ready to restart your - server and try it out. Type: apachectl restart - -4b. Setting up the server. (Static Module) - - You should now have a new httpd binary. Shut down your existing server, - if you have one, and copy this new binary overtop of it. Perhaps make - a backup of your previous one first. Then edit your conf/httpd.conf file - and add the line: - - AddType application/x-httpd-php .php - - There is also an interesting feature which can be quite instructive and - helpful while debugging. That is the option of having colour syntax - highlighting. To enable this, add the following line: + It's also common to setup the .phps extension to show highlighted PHP + source, this can be done with: AddType application/x-httpd-php-source .phps - Any file ending in .phps will now be displayed with full colour syntax - highlighting instead of being executed. - - Note that on some older server setups, the AddType lines are in the - conf/srm.conf file instead of conf/httpd.conf. - - Note! If a line has a # at the beginning, then it is commented out - and you need to remove the # for that line to take effect. - - When you are finished making changes to your httpd.conf file, you need - to copy php.ini-dist to the appropriate place (normally - /usr/local/lib/php.ini) and edit if necessary. You can then - start up your server. - -5. Testing it all worked - - Create a test file named test.php in your web tree somewhere and - put some test PHP tags in it. <?phpinfo()?> is a good first test. - This tag tells PHP to do a braindump and tells you all sorts of things - about itself. - - -WHY DISABLING -fPIC WORKS ON LINUX - - From: Martin v. Loewis <martin@loewis.home.cs.tu-berlin.de> - To: glibc-linux@ricardo.ecn.wfu.edu - Subject: Re: Shared library -shared vs. -fpic - - [In reply to Kaz Kylheku <kaz@ashi.footprints.net>] - - > PIC stands for Position-Independent Code. - - Correct. - - > Code isn't position-independent (or ``relocatable'') cannot be - > loaded at an arbitrary address; - - Wrong. - - > it requires some references to be patched at load time. - - Correct. - - > Shared libraries need to be relocatable because it's not known - > beforehand what address they will be loaded at - - Correct, depending on the meaning of "relocatable". PIC code typically - does not contain relocations; that's why its position-independent. - - > Just because you don't specify -fPIC doesn't mean that the compiler - > won't emit position-independent code; the option prevents it from - > emitting position-dependent code in situations where it otherwise - > would. - - Correct. However, a non-trivial shared library typically won't be - position-independent unless explicitly compiled with - -fPIC. Linux/glibc indeed does not require a shared library to be - position-independent; instead, it will perform the relocations in the - binary, even if they refer to code pages. As a result, those relocated - pages won't be shared across processes, anymore. - - Regards, - Martin - -USING PHP 3 AND PHP 4 AS CONCURRENT APACHE MODULES - - With some (newer) installations of Apache, it's possible to compile both - PHP 3 and PHP 4, and run them concurrently. - - Note, it's only really wise to do this if you need to use the PHP 3 engine - to maintain backwards compatibility. - - To enable it, configure PHP 3 and PHP 4 to use APXS (--with-apxs) and the - necessary link extensions (--enable-versioning). Otherwise, all standard - installations instructions apply. For example: - - $ ./configure \ - --with-apxs=/apache/bin/apxs \ - --enable-versioning \ - --with-mysql \ - - - - - +16. Use your normal procedure for starting the Apache server, e.g.: + + /usr/local/apache2/bin/apachectl start + + Following the steps above you will have a running Apache 2.0 with + support for PHP as SAPI module. Of course there are many more + configuration options available for both, Apache and PHP. For more + information use ./configure --help in the corresponding source tree. + In case you wish to build a multithreaded version of Apache 2.0 you + must overwrite the standard MPM-Module prefork either with worker or + perchild. To do so append to your configure line in step 6 above + either the option --with-mpm=worker or --with-mpm=perchild. Take care + about the consequences and understand what you are doing. For more + information read the Apache documentation about the MPM-Modules. + + Note: To build a multithreaded version of Apache your system must + support threads. This also implies to build PHP with experimental + Zend Thread Safety (ZTS). Therefore not all extensions might be + available. The recommended setup is to build Apache with the + standard prefork MPM-Module. + _________________________________________________________________ + +Caudium + + PHP 4 can be built as a Pike module for the Caudium webserver. Note + that this is not supported with PHP 3. Follow the simple instructions + below to install PHP 4 for Caudium. + + Example 3-8. Caudium Installation Instructions +1. Make sure you have Caudium installed prior to attempting to + install PHP 4. For PHP 4 to work correctly, you will need Pike + 7.0.268 or newer. For the sake of this example we assume that + Caudium is installed in /opt/caudium/server/. +2. Change directory to php-x.y.z (where x.y.z is the version number). +3. ./configure --with-caudium=/opt/caudium/server +4. make +5. make install +6. Restart Caudium if it's currently running. +7. Log into the graphical configuration interface and go to the + virtual server where you want to add PHP 4 support. +8. Click Add Module and locate and then add the PHP 4 Script Support module. +9. If the documentation says that the 'PHP 4 interpreter isn't + available', make sure that you restarted the server. If you did + check /opt/caudium/logs/debug/default.1 for any errors related to + <filename>PHP4.so</filename>. Also make sure that + <filename>caudium/server/lib/[pike-version]/PHP4.so</filename> + is present. +10. Configure the PHP Script Support module if needed. + + You can of course compile your Caudium module with support for the + various extensions available in PHP 4. See the reference pages for + extension specific configure options. + + Note: When compiling PHP 4 with MySQL support you must make sure + that the normal MySQL client code is used. Otherwise there might be + conflicts if your Pike already has MySQL support. You do this by + specifying a MySQL install directory the --with-mysql option. + _________________________________________________________________ + +fhttpd related notes + + 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. + + Note: Support for fhttpd is no longer available as of PHP 4.3.0. + _________________________________________________________________ + +Sun, iPlanet and Netscape servers on Sun Solaris + + 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 Sun Solaris. + + 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. + + You can find more information about setting up PHP for the Netscape + Enterprise Server (NES) here: + http://benoit.noss.free.fr/php/install-php4.html + + To build PHP with Sun JSWS/Sun ONE WS/iPlanet/Netscape webservers, + enter the proper install directory for the --with-nsapi=[DIR] option. + The default directory is usually /opt/netscape/suitespot/. Please also + read /php-xxx-version/sapi/nsapi/nsapi-readme.txt. + + 1. Install the following packages from http://www.sunfreeware.com/ or + another download site: + + autoconf-2.13 + automake-1.4 + bison-1_25-sol26-sparc-local + flex-2_5_4a-sol26-sparc-local + gcc-2_95_2-sol26-sparc-local + gzip-1.2.4-sol26-sparc-local + m4-1_4-sol26-sparc-local + make-3_76_1-sol26-sparc-local + mysql-3.23.24-beta (if you want mysql support) + perl-5_005_03-sol26-sparc-local + tar-1.13 (GNU tar) + 2. Make sure your path includes the proper directories + PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin and make it + available to your system export PATH. + 3. gunzip php-x.x.x.tar.gz (if you have a .gz dist, otherwise go to + 4). + 4. tar xvf php-x.x.x.tar + 5. Change to your extracted PHP directory: cd ../php-x.x.x + 6. For the following step, make sure /opt/netscape/suitespot/ is + where your netscape server is installed. Otherwise, change to the + correct path and run: + +./configure --with-mysql=/usr/local/mysql \ +--with-nsapi=/opt/netscape/suitespot/ \ +--enable-libgcc + + 7. Run make followed by make install. + + After performing the base install and reading the appropriate readme + file, you may need to perform some additional configuration steps. + + Configuration Instructions for Sun/iPlanet/Netscape. Firstly you may + need to add some paths to the LD_LIBRARY_PATH environment for the + server to find all the shared libs. This can best done in the start + script for your webserver. The start script is often located in: + /path/to/server/https-servername/start. You may also need to edit the + configuration files that are located in: + /path/to/server/https-servername/config/. + + 1. Add the following line to mime.types (you can do that by the + administration server): + +type=magnus-internal/x-httpd-php exts=php + + 2. Edit magnus.conf (for servers >= 6) or obj.conf (for servers < 6) + and add the following, shlib will vary depending on your system, + it will be something like /opt/netscape/suitespot/bin/libphp4.so. + You should place the following lines after mime types init. + +Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="/o +pt/netscape/suitespot/bin/libphp4.so" +Init fn="php4_init" LateInit="yes" errorString="Failed to initialize PHP!" [php +_ini="/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. + 3. Configure the default object in obj.conf (for virtual server + classes [version 6.0+] in their vserver.obj.conf): + +<Object name="default"> +. +. +. +.#NOTE this next line should happen after all 'ObjectType' and before all 'AddL +og' lines +Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inik +ey=value ...] +. +. +</Object> + + (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" + 4. 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. + 5. Setup of authentication: PHP authentication cannot be used with + any other authentication. ALL AUTHENTICATION IS PASSED TO YOUR PHP + SCRIPT. To configure PHP Authentication for the entire server, add + the following line to your default object: + +<Object name="default"> +AuthTrans fn=php4_auth_trans +. +. +. +</Object> + + 6. To use PHP Authentication on a single directory, add the + following: + +<Object ppath="d:\path\to\authenticated\dir\*"> +AuthTrans fn=php4_auth_trans +</Object> + + 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. This function uses some undocumented features from the + NSAPI library. On Unix the module automatically looks for the needed + functions and uses them if available. If not, nsapi_virtual() is + disabled. + + Note: But be warned: Support for nsapi_virtual() is EXPERIMENTAL!!! + _________________________________________________________________ + +CGI and commandline setups + + The default is to build PHP as a CGI program. This creates a + commandline interpreter, which can be used for CGI processing, or for + non-web-related PHP scripting. 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 users to run + different PHP-enabled pages under different user-ids. + + 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. + + As of PHP 4.3.0, some important additions have happened to PHP. A new + SAPI named CLI also exists and it has the same name as the CGI binary. + What is installed at {PREFIX}/bin/php depends on your configure line + and this is described in detail in the manual section named Using PHP + from the command line. For further details please read that section of + the manual. + _________________________________________________________________ + +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 3 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. + + Note: make bench is only available for PHP 3. + _________________________________________________________________ + +Using Variables + + Some server supplied environment variables are not defined in the + current CGI/1.1 specification. Only the following variables are + defined there: AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, + GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, + REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, + SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, and + SERVER_SOFTWARE. Everything else should be treated as 'vendor + extensions'. + _________________________________________________________________ + +Chapter 4. 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. 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 5. 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 5-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 5-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(). @@ -33,6 +33,7 @@ PHP NEWS - Fixed ZTS destruction. (Marcus) 13 Jul 2004, PHP 5.0.0 +- Rewritten UNIX and Windows install help files. (Documentation Team) - Updated PCRE to provide better error handling in certain cases. (Andrei) - Changed doc comments to require a single white space after '/**'. (Marcus) - Fixed bug #29019 (Database not closing). (Marcus) 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(). |