The PHP Extension and Application Repository, or PEAR, is a framework and distribution system for PHP code components. Stig S. Bakken founded the PEAR project in 1999 to promote the re-use of code that performs common functions. The project seeks to provide a structured library of code, maintain a system for distributing code and for managing code packages, and promote a standard coding style.

While PEAR is a nifty concept and could be very useful in simplifying and/or speeding up your coding projects, as a DIY webmaster, you will most likely only care about PEAR when you try to use some third party script that requires it and you find out that you don't have it (or that you do but it still doesn't work). For the rest of you who actually want to explore PEAR's usage, I am not the person for that, but there is a PEAR primer you may want to check out.

I suspect webmasters will first become aware of this thing called PEAR if they are trying to use phplist or another mailing program to mail webpages since PEAR is used to fetch the webpage. There are actually several forum threads on PEAR problems in the phplist.org forums but I noticed most don't have any relevant advice on how to get it working. One which does is titled Sending a Web Page. However, that is a multi-page thread that covers several topics and even then the directions are not crystal clear. So, I thought I would write up my solution to the dreaded "PEAR::HTTP/Request is not available" error.

Do I have PEAR installed?

A natural question to ask is whether you already have PEAR installed. In theory, PEAR is installed by default in PHP versions starting with 4.3, though most shared hosting environments don't have PEAR installed. Apparently, it is also fairly common for PEAR to be installed but not the PEAR::HTTP/Request module. There are ways to find out, but my basic attitude is this: if your script isn't working regardless of whether you have PEAR installed or not, manually installing it is probably less hassle than working with your hosting provider to get it all sorted out on their end. And, this will be useful if you later decide to change hosting providers.

Manually installing PEAR

The process for manually installing HTTP_Request isn't that painful. The basic steps are:

1. Download the relevant code. I actually got the core files that you can download here from the Sending a Web Page thread on the phplist forum, so I should acknowledge the source, saul11. The problem with his download is that the files aren't zipped with the proper directory structure. In addition, he didn't provide a test script, so I have added that, though I have forgotten where I picked that one up.
   




2. Upload to your website. These files assume that you will maintain the directory structure, namely a directory called pear in your root directory and a sub-directory called HTTP which further has a sub-directory called Net. If you don't keep this structure you will have problems.
   


3. Test your installation. After you upload the files, open the example.php file in your browser. It should load the php.net webpage in your browser window. If not, you will probably see some PHP errors. If those error(s) say something about openbase_dir then the problem is probably in the include path setting (see below) on line 40 so you can play with that. If some other errors show up you're probably in trouble and may need to contact tech support.
   


4. Set the include path. It is important to tell whatever script that requires HTTP_Request where to find it. Your PHP installation has a default include path, but that won't cover the location of our new files so we have to add the relevant path. This could be done by changing the php.ini file, but it is easier to just use the PHP ini_set command instead. Using phplist as an example, you can add the following line in the config.php file:
   

ini_set("include_path", getenv('DOCUMENT_ROOT').'/pear' . PATH_SEPARATOR . getenv('DOCUMENT_ROOT').'/pear/HTTP' . PATH_SEPARATOR . ini_get("include_path"));

The format of the include_path variable is a list of directories separated by the PHP constant PATH_SEPARATOR which is a colon (":") for unix based systems and a semicolon (";") for Windows systems. A period (".") in the include path would mean the current directory and can be used to allow for relative includes. More information is available at the ini_set page.

Notice that I have specified three separate paths, taking advantage of the getenv('DOCUMENT_ROOT') command, which refers to your root directory (e.g., /var/www/html/, /var/www/vhosts/domain.com/httpdocs/ etc.). Basically, we are telling PHP to search the pear/ and pear/HTTP/ directories when it executes. The third directory specified uses the ini_get("include_path") command, which returns the default include path for your PHP installation.

That should hopefully cover everything. Let me know if I was unclear in my presentation or if I missed anything.

UPDATE

I mentioned taking advantage of the getenv('DOCUMENT_ROOT') command. I have since learned (the hard way, of course) that environment and server variables which are so incredibly useful aren't always available if you are using PHP in the command line mode. I used phplist as an example and, in that case, I use a cron job to regularly process the queue in phplist, but this won't work in my command line setup. I can't speak for the differences between PHP versions, cgi vs. cli, etc., but to be safe I now recommend that you set the include path manually.