Installing PHP5 as a CGI Handler

So you want to install PHP5 as a CGI handler under Apache 1.3 on a RedHat box. Well, I’ve had some success with this, so the following are my notes on how to get it done. I’m going to keep this as basic as I can, as I’d like whomever is reading this to be able to achieve what I was able to; and given that I didn’t have a whole lot of knowledge on how to get this done when I started, I can imagine that there’s a few other people out there who don’t have a clue about it either.

This entire project starts and ends with the .htaccess file that anyone should be able to create and edit in a text editor on their web account. (If you’re not sure what a .htaccess file is, I would suggest reading the Apache Documentation on the subject. )

The end result of this project is that we will add a CGI handler directive to .htaccess which will take care of handling certain PHP files (In this case, those ending in .php or .php5) As Michal Wallace from Cornerhost commented in an e-mail on the subject this past couple weeks, this type of setup also allows for you to have both php4 and php5 running on the same server, giving you the flexibility to run older applications and newer, based entirely on a file’s extension.

Here’s what you should have in (or added to) your .htaccess file for this to work:
AddType application/x-httpd-php .php5
AddHandler application/x-httpd-phpx .php5
Action application/x-httpd-phpx /php5/bin/php

Before any of these .htaccess “directives” will actually do anything for you though, you’re going to need to install PHP5 on your account. (Now, I am assuming that you have Shell Access to your account, and permission to install programs on it. If that’s not the case, you will need to get assistance from your service provider to make this happen.) I used PuTTy to access my account, but another utility will work just as well.

I am going to assume that your account’s directory structure is similar to that of Cornerhost’s and that you can have multiple domains stored in a directory labelled ‘web’. Example:

-- account_ root
  -- web
    -- yourdomain.com
    -- asubdomain.yourdomain.com

The first step to getting PHP5 installed on your account is getting the source code downloaded and uploaded to your account. (I would suggest placing the archive in the ‘web’ directory.) Using either your favourite browser (IE or Mozilla, etc) or Elinks, (I prefer to browse for my downloads using my shell account. It saves having to later upload via FTP the files that I download. As long as you don’t unzip the files on your desktop, you can do it the long way, though.) :) Here’s where you need to go to get the source code: http://www.php.net/downloads.php. (As of the writing of this article, the file that you need to download is PHP-5.1.2.tar.gz. I’m more familiar with .gz archives, so that’s the one I downloaded.)

Once you’ve got the archive downloaded and placed in the ‘web’ folder, it’s time to expand it. These are the commands you need to do it. (By the way, you’re going to want to have navigated to the ‘web’ directory in your SSH client if you haven’t already. cd ./web from account_root):
gunzip php-5.1.2.tar.gz
tar -xf php-5.1.2.tar

If you happen to run into any problems getting these compression utilities to work for you, refer to the following manual pages. There’s a lot of information there for you to go through, but hopefully it will help you understand the program better that you can solve whatever problem it is that you’ve run into. (I’m going to layman-ise these commands for you, so you get the most out of this.):
man gunzip | more
man tar | more

Navigate into the new ‘php-5.1.2′ directory (cd php-5.1.2) and have a look at what’s there (ls -x). You should be looking at a bunch of files that may or may not make a lot of sense to you. (Hopefully they do, because that’ll make this a lot easier for you.) :)

What you are going to do now, is take these source code files and turn them into the actual application that’s going to parse all of your .php5 (or .php) files. It sounds a lot scarier than it actually is; the people behind PHP like to make things relatively easy for less-advanced programmers to get the things that they want out of a project. (I should have perhaps stated earlier on that you are going to need at least some knowledge of what PHP features you’re going to want incorporated into the parser, or at least good intuition as to what you will want installed.) If you have a working knowledge of how ‘configure’ and ‘make install’ work, then this whole compiling thing is old news to you. Skip on down to the details of the .htaccess setup if you like.

Step 1: Configure. I’m not an expert on this, so I apologize if I oversimplify, or err here. Basically, the ‘configure’ command is going to go through the options you give it, and set up the details for the ‘make’ program to compile all the libraries and other things that need to be put together, into the PHP parser. This is also where we tell the compiler that we want it to output the cgi handlers and ignore the rest of the methods for incorporating PHP into a webserver. (There’s a number of different methods for installing php on webservers.)

So, my suggestion here is that you go through ./configure --help | more and write down all the flags (i.e. –help) that you want to give ./configure to achieve the result you want. For instance, if you want to disable all extensions, you are going to want to use the ‘–disable-all’ flag.

A few staple flags that we’re going to need are these:

• –prefix=PREFIX (where PREFIX is the directory where you want to install PHP. In this case we’re going to use /home/account_root/web/php-5.1.2 )
• –host=HOST (where HOST, I believe is your site’s base address . i.e. yourdomain.com)
• –with-libxml-dir=DIR (where DIR is the path to your libxml2 directory. You will need to have libxml2 already installed on your server for this whole thing to work. i.e. /home/account_root/web/libxml2)
• –enable-force-cgi-redirect
• –with-cli (basically, makes sure that we have the cgi handler output)

Whatever other options that you add to the command, here’s the basic format that you’re going to want to work with:

./configure --prefix=/home/account_root/web/php-5.1.2 --host=yourdomain.com --with-libxml-dir=/home/account_root/web/libxml2 --enable-force-cgi-redirect --with-cli

Step 2: Once you’ve successfully configured the compiler to do what you want it to, you’re going to need to run this command:

make install

This will go through all the configurations you requested and put together the necessary libraries and other bits of code into the PHP parser. If you run into any problems here, you’re going to want to have a close look at the error messages that you’re given. (I suggest making sure that you’re SSH client is keeping a log of the output that you’re getting.) PHP5 has a number of dependancies that previous versions didn’t, and you may need to go back and make sure that they’re installed (same basic procedure as this) before you can proceed. If there’s another problem that you’re running into, you may want to consult ‘configure’s –help file again, or see what other online documentation there may be on the problem. (You can also e-mail me at email@chrisbraybrook.com if you would like. I will gladly give you what help I can.)

Step 3: Hopefully you didn’t run into any problems and we can proceed. Getting PHP5 downloaded, configured, and installed is the biggest hurdle that you need to get over in this project. You are also now going to need to familiarize yourself with the contents of the php.ini file, which you should find in the same directory that you installed PHP5 to. This is the configuration file for the PHP parser, and your method of controlling various different settings in PHP. I’m not going to get into php.ini, but I would suggest that you take a look at the php.ini-dist file located in the same directory as php.ini. It should give you some general information about what’s going on. (And if you’re an accomplished PHP programmer, you’ll very likely already know what most of the stuff in php.ini does.)

Now let’s take a look at .htaccess again.

AddType application/x-httpd-php .php5 This directive is fairly straightforward if you read through it. We’re telling Apache that we want it to recognize the files with the extension ‘.php5′ as PHP files, and not text or jpeg files. Simple enough, right?

AddHandler application/x-httpd-phpx .php5 Here, we tell Apache to add a handler called ‘application/x-httpd-phpx’, and that it should be called upon whenever a .php5 file is accessed..

Action application/x-httpd-phpx /php5/bin/php Any time the ‘application/x-httpd-phpx’ handler is called, the page should be parsed by the cgi application ‘php’ at this address:: ‘/php5/bin’. (a.k.a. http://www.yourdomain.com/php5/bin/php)

Here’s the sneaky part. If you’re running in a setup such as I am, and you would like to be able to use this PHP installation across several subdomains and other domains without having to have a separate install for each and every one of them, you’re going to have to do some sweet-talking to your service provider.

In Apache, you can set up a ScriptAlias directive in the main webserver configuration file (httpd.conf), either by itself or in <VirtualHost> (for individual accounts), which tells the webserver that whenever someone makes a call to ‘http://www.yourdomain.com/php5′ they’re actually going to get the designated cgi directory of ‘/home/account_root/web/php-5.1.2′ instead. Hence why ‘/php5/bin/php’ refers to the ‘php’ cgi app in ‘/home/account_root/web/php-5.1.2/bin’.

Having your php installation set up like this allows you to save space and makes upgrades easier. With modifying this setup slightly, and getting a little help from your service provider, you could have php5 installed elsewhere on the server, such that anyone with an account there can add php5 as a cgi handler in their .htaccess file.

That’s all there really is to it. It’s a bit of work, especially if you’re new to the world of compiling things and writing directives in a .htaccess file, but it’s definately worth it. If you have any questions or comments regarding this tutorial, I recommend posting a comment to this blog. I look forward to hearing how things work out, and hope that I was able to help you out a little at least.

Chris Braybrook