Web Development

Application Development: Install PEAR on a shared Web host

The various libraries provided by the PEAR open source project can greatly increase the application development capabilities of PHP. In this article, you'll see how to install the PEAR libraries onto a shared hosting site.

The PEAR (PHP Extension and Application Repository) adds a variety of new capabilities to PHP Web developers' toolkits. The developer becomes a more valuable resource as he adds skills like XML-RPC for Web services, image manipulation, XML insanity, and so on. Using the PEAR libraries means avoiding the reinvention of a whole lot of wheels. Being an open source project, you also get value from a multitude of developers continually making it better.

In this article, you'll see how to install the PEAR libraries on your IPP's (Internet Presence Provider's) shared hosting site. I am assuming that your site is hosted on a *NIX system running Apache since that's how many IPP's set up their service. It's worth pointing out that most shared hosting providers (like SBC, Yahoo!, Angelfire, and many others) that don't make PHP available to their customers won't let you use PEAR either.

Limitations of shared hosts
Normally, installing resource libraries requires you to have some sort of power-user, administrator-only, no-dogs-allowed level of security. Shared hosting providers are particularly skittish about letting folks install libraries because one bad call can bring down an entire Web farm. PHP is nominally safe in these environments—especially on *NIX machines. On a well-managed Web farm, users can't mess with each other's Web sites, and don't have enough access to modify the configuration of the OS and its root applications.

One way this applies to the installation of PEAR is the configuration of PHP "includes". Your shared provider may or may not create a common PHP "include" directory, which is holding libraries available to all users. They also may, or may not, have installed the PEAR libraries. In all likelihood, they did not install PEAR or have a bare-bones installation of an old, deprecated version. That's alright though, because you're better off managing your own installation.

Shared hosting
NOTE: Many shared hosting services do provide the PEAR libraries that are provided with the default installation of PHP. Even if they've done this, you may want to install the latest (or a deprecated) version in order to keep your entire Web project atomic and easy to migrate.

Another issue with installing PEAR on Shared Hosts is CVS (Concurrent Versions System) and CLI (Command Line Interface). If you don't have Telnet access into your Web service, you probably won't be able to take advantage of these remarkably powerful installation interfaces. That's alright too, since you're better off not getting married to these remarkably complex installation interfaces.

There is one, minor downside for the shared hosting provider who doesn't provide PEAR already. If several users each install a copy for their own Web sites, some disk space can be wasted, although, not much. If a couple of hundred PEAR libraries are going to tax their storage capacity, they probably have other problems as well.

For maximum control over your own installation of the PEAR libraries, manually installing your own copy is a good thing.

Manual installation
Now that you know why your shared hosting service probably doesn't already provide you with the PEAR libraries, here's how to get around that limitation. The two ways of installing the PEAR libraries described in the online documentation are via FTP (or WebDAV) and manually. To decide which method to use, you should look at what permissions you have.

XCopy
NOTE: Microsoft's incarnation of this kind of manual installation is nominally known as, "XCopy Installation." It's a feature they've hoped to include in .NET, but missed the mark. Reliance on compiled classes, registry features, and non-OS features has made XCopy installations of Microsoft-based Web applications a rarity.

If your provider allows you FTP access to your Web site, then FTP is the method you should choose. If they have some sort of proprietary interface, usually a drag-and-drop thing, you may need to go full-manual. Either way, if you can upload PHP files to your Web server, you can install the PEAR libraries.

Step 1: Create a secure directory
The first step is to create a directory into which you'll install the PEAR library files. This will be an "include" directory. You should probably name it pear because it's descriptive and one doesn't normally have any other directories by that name off of the Web root.
  1. To create and secure the directory, launch the FTP client and browse to your Web root. The Web root will probably be named something like public_html/mydomain.org.
  2. From there, use the FTP client's commands to create a new directory called pear.
  3. Next, right-click on the PEAR directory and select Properties. You'll see three frames to manage three types of users.
  4. For the World, ensure that Read is disabled (not checked), and that Execute is enabled (checked). This will prevent users from launching the scripts themselves.

Step 2: Download the installation files
The PEAR libraries are many and growing. You can download and install the whole thing, but I don't recommend it. It's hard to conceptualize any project that requires all of the libraries. It would introduce an unnecessary and potentially expensive level of complexity.

The core files for the PEAR library are in the PEAR Base System. The current stable release is PEAR-1.2.1.tgz.

Go-PEAR
An automated option is the Go-PEAR.PHP utility. Go-PEAR is a PHP file that you can download from GO-PEAR.ORG. Oddly enough, you simply save the home to your downloads directory as go-pear.php. Upload the file into the PEAR directory you created in Step 1.

Download for manual installation
You will also want to download any additional packages that you will use. As you download additional packages, you'll find that many, if not most, of the packages are dependent upon other packages—so you'll need to download those dependency packages as well. For example, the PEAR_PackageFileManager utility is dependent upon the PEAR Package 1.1 or newer, so if you want to use it to manage package.xml files, you'll need to ensure that it can access an installation of the appropriate version of the PEAR Base System.

Step 3: Copy the files
I recommend using either WS_FTP or FrontPage to simply drag-and-drop the files and directories from a "gold-code" copy of the PEAR directories on a tested staging server, and out to a production server. If you don't have a staging server, you can manually extract the PEAR installation archive (with directory structure) on your local workstation. Then "XCopy" the whole tree over to your Web server.

Programming with PEAR
If you installed PEAR on a shared host, you probably don't have access to the INI file, to which several modifications may need to be made. That means your PHP pages will not be able to automatically use the PEAR libraries. To correct this, and to PEAR-enable a page, you should add the following code to the top of any PEAR-dependent pages:
<?php
ini_set(
    "include_path", (
        "public_html/kaufman.net/pear/PEAR-1.2.1/" .
        PATH_SEPERATOR .
        ini_get("include_path")
        )
    )
);
?>


This will programmatically add the PEAR directory to the list of directories in which include files will be found. (Of course, you'll want to change line three to the path for your Web directory). You can verify that the modification is successful by checking the value of ini_get("include_path") before and after the ini_set() attempt.

With that bit of code, you can reference PEAR and its various modules by their pathnames, relative to the PEAR root. Referencing the SOAP module, once installed, would use the following command:
1 require_once 'SOAP/soap.php'

If you want to have several versions of PEAR running on the same host, you can do so by simply changing the ini_set() function to reference the appropriate version's path.

PEAR power
You now have access to a variety of minimally useful functions. However, the real power is in the additional packages that are available. I've met developers who knew little more than the PEAR DB libraries, yet were productively employed. The various packages include utilities for building just about any kind of Internet application—including e-mail, encryption, database management, image management, and numerous other applications.
3 comments
callmahais
callmahais

can any help me with this. below error shows up whenever i develop a page with pear application: Warning: require_once(DB.php) [function.require-once]: failed to open stream: No such file or directory in C:\Program Files\Apache Group\Apache2\htdocs\mahais\createtable.php on line 6 Fatal error: require_once() [function.require]: Failed opening required 'DB.php' (include_path='.;c:\php\includes;c:\php\PEAR') in C:\Program Files\Apache Group\Apache2\htdocs\mahais\createtable.php on line 6

Bucky Kaufman (MCSD)
Bucky Kaufman (MCSD)

It *seems* to be pretty self-explanatory. The db.php file is missing. Maybe it never got copied; maybe permissions are off; maybe it got renamed; maybe you setup an alias somewhere that's since been changed. Could be a lotta stuff. :(

Editor's Picks