C.2 Module and CGI

Installing PHP 5 as a CGI is a quick way to get up and running without sacrificing PHP 4. This section describes two techniques for making PHP 5 parse your code, instead of PHP 4.

Remember that the CGI version of PHP has a few limitations compared to the Apache module version. It cannot hook into HTTP Basic Authentication, nor can you read and write internal Apache values using functions such as apache_note( ) .

One option is to enable PHP 5 on a directory-by-directory basis. This lets the PHP 4 module handle scripts by default, but lets you slowly release PHP 5 code when it's ready.

The second alternative is to enable PHP 5 for all files but on another port. By default, Apache listens for requests on port 80, so normal requests are still handled as usual. However, whenever a request is made to your site on port 8080, Apache now hands the script off to PHP 5. With this setup, you can easily get a complete overview of your PHP 5 compatibility without sacrificing PHP 4 support.

This process breaks down into two main parts : configuring PHP 5 and configuring Apache. The PHP 5 configuration is identical for either Apache setup, so you can easily switch between the two.

C.2.1 Configuring PHP 5 as a CGI

Installing PHP 5 as a CGI requires four additional steps beyond your normal configuration:

1. Remove --with-apxs .

2. Add --enable-force-cgi-redirect .

3. Add --prefix=/usr/local/php5 .

4. Customize php.ini .

PHP defaults to a CGI installation, but it won't build it when you specify a web server module. Therefore, it's important to remove the call to --with-apxs (or whatever your specific web server is). Also, for security reasons, you should always add --enable-force-cgi-redirect when building PHP as a CGI. This prevents people from directly accessing your PHP CGI.

When adding PHP 5 to your system, it's important not to overwrite the PHP 4 files and configuration data. The two must coexist because you're not ready to eliminate PHP 4. Use the --prefix configuration option to force PHP to install PHP 5 in a separate directory hierarchy. The example in this section uses /usr/local/php5 , but any directory will work. Remember this location because you need to use it to let Apache know the location of the PHP CGI. After adding this to your PHP configuration, make and install PHP as normal.

The final step is customizing your php.ini file. First, copy php.ini-recommended to /usr/local/php5/lib/php.ini . PHP 5 has new configuration options, so you should use this file as your base. Then, migrate over any changes you've made to your PHP 4 php.ini file to the PHP 5 version.

C.2.2 Directories

The first step to enabling PHP 5 on a directory-by-directory basis is creating a mapping between a location on your web server and the PHP CGI. To do this, add the following commands to your Apache httpd.conf file:

 ScriptAlias /php5 /usr/local/php5/bin <Directory /usr/local/php5/bin/>     Options +ExecCGI +FollowSymLinks     AllowOverride None </Directory> 

The ScriptAlias line links the web server's /php5 directory and /usr/local/php5/bin on your machine. (If you've installed PHP 5 someplace else, alter this line accordingly .) Now, whenever you access a file from http://www.example.com/php5, Apache executes the file stored in /usr/local/php5/bin instead.

With this redirection established, the next step is to force Apache to route files ending with a particular extension to the PHP CGI. You want to limit this, however, to specific directories. This can be done in one of two ways: placing the information inside a <Directory> section in httpd.conf or adding it to a .htaccess file.

Here's how to do this inside httpd.conf for all files inside the directory /www/www.example.com/php5-folder :

 <Directory /www/www.example.com/php5-folder>     AddHandler php-cgi-script .php     Action php-cgi-script /php5/php     Options +ExecCGI </Directory> 

The AddHandler directive says that any file ending in .php should be considered a php-cgi-script . The term php-cgi-script isn't a special name , but merely a unique way to identify the files to be parsed by PHP 5. You can place additional extensions on this line, like so:

 AddHandler php-cgi-script .php .html 

Now files ending in .php or .html will be parsed.

The second line adds an Action directive. This directive tell Apache that all php-cgi-script s should be handled by the file located at /php5/php. Since you've previously said that all files in /php5 go to /usr/local/php5/bin , this command effectively passes the script to /usr/local/php5/bin/php . By a happy coincidence , this is the location where PHP 5 installed the CGI.

Last, since you're running PHP 5 as a CGI script, you need to add +ExecCGI to your Apache Options to make the script execute.

An alternative approach is to place the middle three lines inside a .htaccess file. This is a special file read by Apache where you can modify a limited set of Apache (and PHP) settings. There's no need to wrap them inside a <Directory> section, because Apache automatically assumes the current location.

Using .htaccess allows you to modify settings without restarting Apache; however, it requires you to enable the AllowOverride option. This can slow down Apache because it now must check for and parse these files on every request.

C.2.3 Ports

Another way to provide simultaneous PHP 4 and PHP 5 support is to run PHP 4 on one port and PHP 5 on the other. This is best used for internal debugging on development and staging servers, to allow programmers to easily check the status of a program under PHP 5.

The first step is to add a Listen directive to httpd.conf :

 Listen 80 Listen 8080 

By default, Apache (like all web servers) listens on port 80. These lines tell Apache to also listen on port 8080. Again, there's nothing particular about the number 8080, except that it's greater than 1024 and doesn't conflict with another program. (Port numbers lower than 1024 are reserved for official use.) Many people choose 8080 because it's a doubling of the official HTTP port.

Now you need to set up the CGI on port 8080. This is done using an Apache virtual host:

 <VirtualHost _default_:8080>     ScriptAlias /php5 /usr/local/php5/bin     <Directory /usr/local/php5/bin/>         Options +ExecCGI +FollowSymLinks         AllowOverride None     </Directory>              AddHandler php-cgi-script .php     Action php-cgi-script /php5/php     Options +ExecCGI </VirtualHost> 

These commands are identical to the ones in the previous section, except that they're applied to all files, not just ones in a particular directory or directories.

This <VirtualHost> section matches all requests handled by Apache running on 8080 that aren't already processed by a different virtual host. When you're running multiple virtual hosts , you should substitute the hostname for _default_ .

Also, if you're using multiple virtual hosts, you need to copy options, such as DocumentRoot , from the PHP 4 virtual host to the PHP 5 host. For example:

 <VirtualHost www.example.com:80>     # Virtual Host Specific Options     DocumentRoot /www/www.example.com     # Load PHP 4 Apache Module     LoadModule php4_module /usr/lib/apache/1.3/libphp4.so </VirtualHost> <VirtualHost www.example.com:8080>     # Repeated Configuration Options     DocumentRoot /www/www.example.com     # Add PHP 5 CGI Script     ScriptAlias /php5 /usr/local/php5/bin     <Directory /usr/local/php5/bin/>         Options +ExecCGI +FollowSymLinks         AllowOverride None     </Directory>              AddHandler php-cgi-script .php     Action php-cgi-script /php5/php </VirtualHost> 

When you go to any page under http://www.example.com/ , you still see the PHP 4 version. However, http://www.example.com:8080/ now delivers a PHP 5 version.