PHP

PHP is a widely-used general-purpose scripting language that is especially suited for Web development and can be embedded into HTML. This makes it suitable for embedding small pieces of dynamic content into web pages, although it is also being used for much more complex web applications. PHP versions 3, 4 and 5 are all available for use with your account. This page gives details on how to set up your webspace for use with PHP. For more details on programming with PHP, please see the PHP homepage.

PHP is widely used as an Apache module, known as mod_php, but for security reasons we cannot offer this service (more details). Instead, we make PHP available via CGI using a standalone interpreter. In most cases, no changes to your scripts will be necessary. If CGI isn't fast enough for your site (unlikely for most sites), you can arrange to run your PHP scripts as persistent FastCGI processes.

Using PHP

To use PHP, your scripts should generally have a .php extension. For newly-created accounts, this will cause them to run under PHP 5. (Other versions are also available.)

The scripts must be executable. You can make a script executable using the chmod command (e.g. chmod a+x myscript.php). To find and make all scripts executable, you can use a command such as:

find ~/www.mydomain.com_html/ -name \*.php -print0 | xargs -0r chmod a+x

The permissions and ownership on your PHP scripts is subject to the same restrictions as other CGI scripts.

You must now arrange for your scripts to be treated as CGI scripts by the web server. The simplest way to do this is to place them in your cgi-bin directory. It is also possible to make PHP scripts in other directories executable. This can usually be achieved by creating a file called .htaccess in the directory containing the text:

AddHandler cgi-script .php
Options +ExecCGI

If this does not work, you may not have the required permission on your virtual web server. Please email us and we will be happy to make the change to the configuration.

Configuring a specific version of PHP

During recent years PHP has evolved considerably, and scripts written to use PHP 3 will not necessarily run under PHP 5 and vice versa. If you need to use a different version of PHP, there are several ways to do this. Scripts with the extension .php3, .php4 or .php5 are run under appropriate version. Giving the scripts a version-specific extension is one way to select the version of PHP used.

For all newly-created shell accounts, scripts with the extension .php will be run as PHP 5; some older accounts defaulted to PHP 4. (To see what version of PHP your scrips default to, type php-binfmt -v.) You can change the default version of PHP by running the following

mkdir -p ~/.alternatives
ln -sf /software/bin/php5 ~/.alternatives/php
ln -sf /software/bin/php5 ~/.alternatives/php-binfmt

Change php5 to php3 or php4 in the above if you want an older version of PHP. Note that this will affect all sites hosted on your account.

If you want to change the version of PHP used by files with a .php extension for all or part of a website without affecting other sites hosted on your account, you can do this by creating a specific .alternatives directory for this one account:

mkdir -p ~/.alternatives
cp -r ~/.alternatives ~/.alternatives-for-my-site
ln -sf /software/bin/php5 ~/.alternatives-for-my-site/php
ln -sf /software/bin/php5 ~/.alternatives-for-my-site/php-binfmt

Then create a file called .htaccess in the directory containing the site or part of the site that you want to run with a different version of PHP. This should contain the following line:

SetEnv HTTP_ALTERNATIVES_DIR /home/username/.alternatives-for-my-site

Using a `php.ini` file

Occasionally it is necessary to override some of PHP's configuration parameters. This can be done by creating a php.ini file to override the system default values. Ordinarily, the php.ini file must be in the same directory as the PHP script that is being run.

If you have a large site with many directories, maintaining copies of php.ini in each directory can be a nuisance. One stategy is to have a single copy of the file and invoke PHP with the -c option to reference this copy. To do this, create a wrapper script around PHP called (say) php-wrapper:

#!/bin/sh
exec /software/bin/php5 "$@" -c /path/to/php.ini

and set up .alternatives to recognise this:

mkdir -p ~/.alternatives
ln -sf /path/to/php-wrapper ~/.alternatives/php
ln -sf /path/to/php-wrapper ~/.alternatives/php-binfmt

Some users maybe familiar with the php_value directive used in .htaccess files as an alternative way of overriding PHP's configuration settings. This is specific to mod_php and therefore does not work on our servers.

Why can't I use mod_php?

It is not possible to make mod_php available on your account in a secure fashion, as your account is hosted on a shared server. Many users' webpages are served by the same server process. The webserver is configured to run any CGI scripts under the user id of the owner of the webpage, rather than the user id of the web server process. This means that your CGI scripts need only be readable by your user id, so it is possible to include sensitive data (such as database passwords) safely in your scripts, and other users will not be able to access it.

It is not possible to configure the web server to run mod_php scripts under a different user id, as they are, by design, run as part of the server process. This means that all users' scripts would be run under the same user id, and it would be impossible for them to safely include sensitive data. Having user scripts executed under the same user id as the web server process also has other security implications on a shared system.

Using FastCGI with PHP

If you expect very heavy traffic for your site, you can improve the performance of your site by running the PHP interpreter as a "FastCGI" process. This should achieve acceptable performance even for very busy sites (in tests, we've found that rates of 50 to 100 requests/second can easily be sustained). But this configuration is a bit more complicated, so we recommend that you do not use it unless your site is busy enough to need the extra performance.

FastCGI is a protocol which allows a web server such as apache to invoke another program to serve a page, but without the overhead of CGI (which needs to fork a process for every request) or the security problems of running scripts in-process in the web server (discussed above). PHP versions 4 and later support FastCGI in one of two modes:

run a handler for each PHP page as a separate process;
run one or more PHP interpreters, each of which can serve any PHP page.

The second of these is almost always better, for obvious reasons, and it is the configuration we describe here. (Note that these instructions assume that your website is configured in a fairly straightforward way. You'll need to adapt them as necessary for more sophisticated setups.)

To set this up, start by creating a directory called fcgi in the root of your web site. Inside it create a script called php, containing the following:

#!/bin/sh
PHPRC=/etc/php5/fcgi exec /software/bin/php5 "$@"

and make it executable. (We use a wrapper script rather than a symlink because apache is very picky about file permissions and symbolic links. The assignment of the PHPRC environment variable is required to make PHP read a slightly different configuration file, since the value of the cgi.fix_pathinfo must be 1 for FastCGI and 0 for normal CGI.) Also create a .htaccess file in the same directory:

Options +ExecCGI
SetHandler fastcgi-script

which tells apache to run scripts in the /fcgi/ directory as persistent FastCGI processes. The next step is to have your individual PHP files processed using this interpreter. To do this, add the following lines to a .htaccess file in the root directory of your site (create one if none already exists):

AddType application/x-httpd-fastphp .php
Action application/x-httpd-fastphp /fcgi/php

And once you've done that, everything should Just Work.

Testing it first

But... since you probably want to make sure that nothing on your site breaks when you make this change, here's a simple way to test everything first without disturbing the normal operation of your site.

First, make a copy of all (or some) of your .php pages under new names ending .qhq, for instance with this shell command:

for phpfile in `find . -name '*.php'`
do
qhqfile=$( echo $phpfile | sed 's/\.php/.qhq/' )
cp $phpfile $qhqfile
done

Now we have apache interpret these files using the FastCGI PHP interpreter. Add the following to a .htaccess file in the root directory of your website:

AddType application/x-httpd-fastphp .qhq
Action application/x-httpd-fastphp /fcgi/php

Now try browsing some of the .qhq files you've just created. If everything is working properly, they should work exactly like their .php counterparts. If not, you'll need to debug the problem, presumably by reading the messages logged to your server's error log. Many common problems are the result of incorrect ownership and permissions of the .../fcgi/php and the individual .qhq files.

Once that's all working, you can change the AddType line in the root .htaccess file to refer to .php files, and everything should be ready to go. Having done that, delete the .qhq files:

find . -name '*.qhq' | xargs rm

and you're all set.