Chapter 67. Installation

The following answer is based in this modified excerpt of a mail by Rasmus Lerdorf.

Apache 2 is a complete rewrite and a complete architecture change from Apache 1. It is not like going from PHP 3 to PHP 4 or from PHP 4 to PHP 5. There is a lot of code that is common, and certainly the base architecture of PHP has not changed for years. So comparing Apache 1 vs. Apache 2 to PHP 4 vs. PHP 5 makes no sense. The architecture has been proven over the years and the code, while somewhat unwieldy in places, is a known entity. PHP from the very early days was designed against this basic Apache 1 architecture and works extremely well running under it.

The major feature that draws people to Apache 2 is threading. On Windows where most basic libraries are, and must be, threadsafe, Apache 2 does actually make sense and it would be good to work out the kinks on that platform. However, on UNIX there are a lot of basic libraries where thread safety is an unknown. And this is not about PHP extensions, it is about 3rd-party libraries underneath PHP's hundreds of extensions. Whether any one 3rd-party library is threadsafe is really hard to determine. There are a lot of variables involved, including which OS, which version of the OS, which libc, which version of that libc and on some platforms even the compiler flags used to compile these things. And to make it even more fun, tracking down a thread safety problem is damn well near impossible. Hundreds of people may well state that Apache+PHP+ext/foo works perfectly for them, but maybe they are only getting about a million hits a day. Then another user comes along who gets 100 million hits a day and uses a fast dual-cpu machine and everything blows up because now suddenly the window for some tiny race condition has been made much larger due to the faster cpu speeds, the second cpu and the higher frequency of requests. And the bug report we get from this user will be something along the lines of:

It don't work sometimes. Most of the times it works fine, but then every now and then it just don't. The error is different each time and I have no idea how to reproduce it, but fix it right away!!!

What can we do about these?

There are a number of (fixable) technical reasons Rasmus does not think Apache2+PHP is a good idea in a production environment, but setting those aside it really boils down to one simple concept:

PHP is glue. It is the glue used to build cool web applications by sticking dozens of 3rd-party libraries together and making it all appear as one coherent entity through an intuitive and easy to learn language interface. The flexibility and power of PHP relies on the stability and robustness of the underlying platform. It needs a working OS, a working web server and working 3rd-party libraries to glue together. When any of these stop working PHP needs ways to identify the problems and fix them quickly. By making the underlying framework more complex by not having completely separate execution threads, completely separate memory segments and a strong sandbox for each request to play in, a feet of clay is introduced into PHP's system.

Using the prefork mpm with Apache 2 to avoid the threading is possible, and yes using a standalone fastcgi mechanism to avoid the threading, too, but then defining characteristic of the web server of choice are avoided. At this point in its development, Rasmus still maintains that one is better off simply sticking with Apache 1 for serving up PHP pages with the one caveat that Apache 1 sucks pretty badly on Windows.

By default on Unix it should be in /usr/local/lib which is <install-path>/lib. Most people will want to change this at compile-time with the --with-config-file-path flag. You would, for example, set it with something like:

--with-config-file-path=/etc

And then you would copy php.ini-dist from the distribution to /etc/php.ini and edit it to make any local changes you want.

--with-config-file-scan-dir=PATH

On Windows the default path for the php.ini file is the Windows directory. If you're using the Apache webserver, php.ini is first searched in the Apaches install directory, e.g. c:\program files\apache group\apache. This way you can have different php.ini files for different versions of Apache on the same machine.

See also the chapter about the configuration file.

This probably means that PHP is having some sort of problem and is core-dumping. Look in your server error log to see if this is the case, and then try to reproduce the problem with a small test case. If you know how to use 'gdb', it is very helpful when you can provide a backtrace with your bug report to help the developers pinpoint the problem. If you are using PHP as an Apache module try something like:

• Stop your httpd processes

• gdb httpd

• Stop your httpd processes

• > run -X -f /path/to/httpd.conf

• Then fetch the URL causing the problem with your browser

• > run -X -f /path/to/httpd.conf

• If you are getting a core dump, gdb should inform you of this now

• type: bt

• You should include your backtrace in your bug report. This should be submitted to http://bugs.php.net/

If your script uses the regular expression functions (ereg() and friends), you should make sure that you compiled PHP and Apache with the same regular expression package. This should happen automatically with PHP and Apache 1.3.x

Assuming you installed both Apache and PHP from RPM packages, you need to uncomment or add some or all of the following lines in your httpd.conf file:

# Extra Modules AddModule mod_php.c AddModule mod_php3.c AddModule mod_perl.c # Extra Modules LoadModule php_module modules/mod_php.so LoadModule php3_module modules/libphp3.so # for PHP 3 LoadModule php4_module modules/libphp4.so # for PHP 4 LoadModule perl_module modules/libperl.so

And add:

AddType application/x-httpd-php3 .php3 # for PHP 3 AddType application/x-httpd-php .php # for PHP 4

... to the global properties, or to the properties of the VirtualDomain you want to have PHP support added to.

Due to the way PHP 3 built, it is not easy to build a complete flexible PHP RPM. This issue is addressed in PHP 4. For PHP 3, we currently suggest you use the mechanism described in the INSTALL.REDHAT file in the PHP distribution. If you insist on using an RPM version of PHP 3, read on...

The RPM packagers are setting up the RPMS to install without database support to simplify installations and because RPMS use /usr/ instead of the standard /usr/local/ directory for files. You need to tell the RPM spec file which databases to support and the location of the top-level of your database server.

This example will explain the process of adding support for the popular MySQL database server, using the mod installation for Apache.

Of course all of this information can be adjusted for any database server that PHP supports. We will assume you installed MySQL and Apache completely with RPMS for this example as well.

• First remove mod_php3 :

  rpm -e mod_php3

• Then get the source rpm and INSTALL it, NOT --rebuild

  rpm -Uvh mod_php3-3.0.5-2.src.rpm

• Then edit the /usr/src/redhat/SPECS/mod_php3.spec file

  In the %build section add the database support you want, and the path.

  For MySQL you would add --with-mysql=/usr The %build section will look something like this:

  ./configure --prefix=/usr \ --with-apxs=/usr/sbin/apxs \ --with-config-file-path=/usr/lib \ --enable-debug=no \ --enable-safe-mode \ --with-exec-dir=/usr/bin \ --with-mysql=/usr \ --with-system-regex

• Once this modification is made then build the binary rpm as follows:

  rpm -bb /usr/src/redhat/SPECS/mod_php3.spec

• Then install the rpm

  rpm -ivh /usr/src/redhat/RPMS/i386/mod_php3-3.0.5-2.i386.rpm

No, PHP works fine with the FrontPage extensions. The problem is that the FrontPage patch modifies several Apache structures, that PHP relies on. Recompiling PHP (using 'make clean ; make') after the FP patch is applied would solve the problem.

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.

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 the PHP executable (php.exe on Windows) and run php -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, and your problem may be related to your server configuration which you should double check.

This has actually nothing to do with PHP, but with the MySQL client libraries. Some need --with-zlib, others do not. This is also covered in the MySQL FAQ.

This error message means that PHP failed to output anything at all. To get to see a sensible error message, from the command line, change to the directory containing the PHP executable (php.exe on Windows) and run php -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.

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

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

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

Make sure any user who needs to run a PHP script has the rights to run php.exe! IIS uses an anonymous user which is added at the time IIS is installed. This user needs rights to php.exe. Also, any authenticated user will also need rights to execute php.exe. And for IIS4 you need to tell it that PHP is a script engine. Also, you will want to read this faq.

You must set the cgi.force_redirect directive to 0. It defaults to 1 so be sure the directive isn't commented out (with a ;). Like all directives, this is set in php.ini

Because the default is 1, it's critical that you're 100% sure that the correct php.ini file is being read. Read this faq for details.

To be sure your php.ini is being read by PHP, make a call to phpinfo() and near the top will be a listing called Configuration File (php.ini). This will tell you where PHP is looking for php.ini and whether or not it's being read. If just a directory PATH exists than it's not being read and you should put your php.ini in that directory. If php.ini is included within the PATH than it is being read.

If php.ini is being read and you're running PHP as a module, then be sure to restart your web server after making changes to php.ini

On Windows NT, 2000, XP and 2003:

• Go to Control Panel and open the System icon (Start -> Settings -> Control Panel -> System, or just Start -> Control Panel -> System for Windows XP/2003)

• Go to the Advanced tab

• Click on the 'Environment Variables' button

• Look into the 'System Variables' pane

• Find the Path entry (you may need to scroll to find it)

• Double click on the Path entry

• Enter your PHP directory ant the end, including ';' before (e.g. ;C:\php)

• Press OK and restart your computer

On Windows 98/Me you need to edit the autoexec.bat file:

• Open the Notepad (Start -> Run and enter notepad)

• Open the C:\autoexec.bat file

• Locate the line with PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;..... and add: ;C:\php to the end of the line

• Save the file and restart your computer

The PHP manual used to promote the copying of files into the Windows system directory, this is because this directory (C:\Windows, C:\WINNT, etc.) is by default in the systems PATH. Copying files into the Windows system directory has long since been deprecated and may cause problems.

There are several ways of doing this. If you are using Apache, read their installation specific instructions (Apache 1, Apache 2), otherwise you must set the PHPRC environment variable:

On Windows NT, 2000, XP and 2003:

• Go to Control Panel and open the System icon (Start -> Settings -> Control Panel -> System, or just Start -> Control Panel -> System for Windows XP/2003)

• Go to the Advanced tab

• Click on the 'Environment Variables' button

• Look into the 'System variables' pane

• Click on 'New' and enter 'PHPRC' as the variable name and the directory where php.ini is located as the variable value (e.g. C:\php)

• Press OK and restart your computer

On Windows 98/Me you need to edit the autoexec.bat file:

• Open the Notepad (Start -> Run and enter notepad)

• Open the C:\autoexec.bat file

• Add a new line to the end of the file: set PHPRC C:\php (replace C:\php with the directory where php.ini is located)

• Save the file and restart your computer

If links to PHP files include extension, everything works perfect. This FAQ is only for the case when links to PHP files don't include extension and you want to use content negotiation to choose PHP files from URL with no extension. In this case, replace the line AddType application/x-httpd-php .php with:

# PHP 4 AddHandler php-script php AddType text/html php # PHP 5 AddHandler php5-script php AddType text/html php

This solution doesn't work for Apache 1 as PHP module doesn't catch php-script.