Installing extensions on shared hosts

I have a hosting account with Site5. I must say there service, though sometimes delayed by the difference in time zones, is generally excellent and they have a large community of users in their forums who will often help you out too.

Recently I had a need to not only use php5 but to also install the bz2 php extension on my account. This proved to be an interesting adventure and since I found very little help on the forums and the need was beyond the scope of the support I bumbled along on my own. I used various resources and finally got it right. Here’s how:

P.S. You’ll need Command-line access to your server (eg: via SSH).

1. Using php5 on Site5

Site5 has both php4 and php5 installed. By default your scripts are executed using php4 however there are a number of ways to force the server to interpret the scripts using php5. The easiest of thses is to use a .htaccess file in the root folder of your app/site. By adding the following lines to the file I forced all .php files to be interpreted by Apache using php5.

AddHandler application/x-httpd-php5 .php

The problem is that even though this will work for Apache it doesn’t help us when we are executing php on the command-line. But we’ll sort this out a little bit further down the road.

2. Getting the extension

Usually if you have command line access you can simply run:

pecl install bz2

This will download the extension, compile it for the local machine and install it. The problem is that when you are accessing a shared server you seldom have sufficient privileges for the process to complete and as such it fails miserably.

So, we are forced to download the extension manually. As mentioned already, most of our hassles are due to permissions. As such I find it easiest to just re-create the necessary basic linux folder structure in our own home folder where we have permission to do as we wish!

I have created the following folders:

mkdir ~/bin
mkdir ~/bin/php5
mkdir ~/bin/php5/extensions
mkdir ~/tmp
mkdir ~/etc

The ~ is a short-cut to your home directory. So the true path to ~/bin is usually (well it is on my Site5 server) /home/username/bin. So now all we have to do is download the extension to ~/etc.

All php extensions can be downloaded from pecl.php.net. I’d recommend that if you are having issues with dependencies you check the site and ensure your installed extension does not have a dependency that is not installed. The exact url for your extension will be http://pecl.php.net/get/extension_name so for our bz2 extension we execute the following on the command line:

cd ~/etc
wget http://pecl.php.net/get/bz2

You should now have a file in your ~/etc directory called bz. So it’s time to unpack it. The files come tarred and zipped so we use the following command to restore them to their full glory:

tar -xzf bz2

Check the directory again. You’ll notice there is now a folder with the name of the extension and the version. In my case it’s bz2-1.0. Now things start to get a bit spicy.

3. Setting php5 as your default command-line executable

For users who only have one version of php on their server this step is unnecessary but for those of us on site5 who want to use php5 we have to get clever.

The first thing we have to do is find out where our php5 executables are located. The easiest way to do this is to execute the built in phpinfo() command. Create a quick php file in your webroot and add this line:

Visit the page in your browser and you should get a page that tells you all about your current php installation. The first thing to do is check that your page is being executed by the version of php you want. This is displayed at the top of the page. Next browse down a few lines for a line that says Configure Command. These are the parameters that were used to compile your php executable. One of the parameters will be –exec-prefix parameter which is the path of the executables. The tricky this is that we are actually looking for the bin directory at this path.

In my situation the –exec-prefix parameter is /usr/local/php5. So what i’ve done is changed my working directory to this one, and listed the contents of the folder:

cd /usr/local/php/bin
ls -l

There are 3 executables in here that I need: php5, php-config5 and phpize5. At the moment if I try to run php from the command line it uses php4. You can check which version you are using by executing:

php -v

I actually want to execute /usr/local/php5/bin/php5. So what I’m gonna do is create links in ~/bin to the executables I need. So lets move to that directory and create the 3 symbolic links we need.

cd ~/bin
ln -s /usr/local/php5/bin/php5 php
ln -s /usr/local/php5/bin/php-config5 php-config
ln -s /usr/local/php5/bin/phpize5 phpize

So now if we execute:

./php -v

We see that we are executing our php5 executable. But this will only work from within this directory. So we need to change the default path linux uses to find these executables. We want to edit the $PATH environment variable. In most instances we can do this by editing our ~/.bash_profile file so we run:

pico ~/.bash_profile

You need to find a line that starts with PATH=. At Site5 my default settings look like this:

PATH=$PATH:$HOME/bin

What this means is the system sets my PATH environment variable equal to the default system PATH and then appends ~/bin onto the end (~ is the same as $HOME). Unfortunately this means that when it looks for the php executable it looks in the default system bin folder and finds the php4 executable first before it finds our newly created link to our php5 executable. So we change the line to:

PATH=$HOME/bin:$PATH

Save the file. To effect the change you’ll need to reload your session. I just logged out and back in to be sure. Then just to be sure the change has taken effect I type:

echo $PATH

You should see something like:

/home/username/bin:/usr/local/bin:/bin:/usr/bin

So now when you check the version of your default php executable you should see that it is now using php5.

php -v

Yippee! Time to compile our extension.

4. Compiling the extension

Now that we know we’re using all the right executables on the command line we can prepare our extension. Go to the directory where our extension was unpacked:

cd ~/etc/bz2-1.0

Use the phpize function to get us ready for configuration.

phpize

The function will output a few lines from which you can determine which API version your extension will be compiled for. So we are ready to run the configure command which will produce the Makefiles so we can compile our extension. If there are any configuration directives you want to include this is where you will do it. For our sakes we just want to ensure that from here on in the process uses the correct folders. So we execute:

./configure

Almost there. Unfortunately our Makefile isn’t 100% ready.

pico Makefile

Look for the line that starts with:

EXTENSION_DIR = /

Delete the path that is there and replace it with:

EXTENSION_DIR = /home/username/bin/php5/extensions

Let’s go:

make
make install

Would you believe it. We’re almost done. The extension is now there but we need to edit our php configuration file to use the extension. On most shared hosts you cant edit the default php.ini but you can usually create your own. On the Site5 servers we simply include our own php.ini at the web root. So first I changed to that directory:

cd ~/public_html

Now we need a copy of the default php.ini. If you go back to the test page we created earlier that displays your php configuration you’ll find the path to the php.ini being used. On Site5 my php configuration file is at: /usr/local/Zend/etc/php.ini. So I execute:

cp /usr/local/Zend/etc/php.ini .

Now I’ve got an exact copy of the default php.ini so I can edit this.

pico php.ini

Find the line that starts:

extension_dir = "./"

Replace it with:

extension_dir = "/home/username/bin/php/extensions"

Then you need to include the following line so that the system loads your new extension:

extension=bz2.so

And thats it! All done. Reload your phpinfo() pageand somewhere down there you should see that your extension has now been loaded.