Getting Started with PEAR - PHP's Low Hanging Fruit

Installing PEAR

OK, enough talk. It's time for some action!

Setting up PEAR and being able to retrieve packages from it is a two-stage process. First, there's the PEAR Installer, then, there's the PEAR Package Manager. The job of the Installer is purely to set up the Package Manager. The Package Manager is the tool you use to fetch the PHP libraries (PEAR packages) you're interested in.

Let's begin with the PEAR Installer. Essentially, it's just a PHP script that connects to the PEAR Website and downloads a whole bunch of other stuff (in particular, the Package Manager). To execute the installer, you need to be able to run PHP from the command line. So, let's start there...

Command Line PHP

If you're running Windows, open up a DOS shell (Windows NT / 2000 / XP: Start > Run > cmd.exe, Windows 95 / 98: Start > Run > command.exe -- see Kev's Command Prompt Cheat Sheet if you're in any doubt).

If you're running Linux on your own PC, I'll assume you know how to start a shell. If you have a LAMP host (Linux / Apache / MySQL / PHP), when you start an ssh or telnet session to the server (assuming your host allows this), you should be taken to the command prompt (typically the BASH shell for Linux). Apologies to Mac users (there's a significant Mac / PHP user group, you know) but Santa failed to leave one in my stocking last December. Maybe next year.

Whatever your OS, from the command prompt, type:

php -v

In response, you should see some version information displayed about PHP, such as:

PHP 4.3.4 (cli) (built: Nov 26 2003 10:46:59)  
Copyright (c) 1997-2003 The PHP Group  
Zend Engine v1.3.0, Copyright (c) 1998-2003 Zend Technologies

If you can't see this, you first need to locate the PHP executable and add it to your systems path variable.

On Windows based systems, this will be below your PHP installation directory, in the "cli" subdirectory, for example:

c:\php-4.3.2-Win32\cli\php.exe

On Linux based systems, PHP will typically be found at:

/usr/local/bin/php

Note that the php binary doesn't have the ".exe" extension on Linux. If in doubt, you can locate it on Linux with the following:

$ whereis php

Failing that, try the following (to search below the /usr directory):

$ find /usr -name php

Now you know where the php executable can be found, you need to update your path variable to make it available.

On Windows, head to Start > Control Panel > System > Advanced > Environment Variables. Scroll down the list of "system variables" until you find the path variable, select it and click edit. Now, at the end the "Variable Value", append the path to your php executable e.g. ";c:\php-4.3.2-Win32\cli\" (note the semi colon, which separates one path from the next). The executable is now in your path. If you start a new command prompt (any existing ones will still be using the old path variable), you should be able to type "php -v" and get the expected response.

If you use a LAMP host, they should have set it up for you, but if not, you need to edit (or create) the file ".profile" in your account's home directory, adding the following line to the end of the file:

export PATH=$PATH:/usr/local/bin

Logout and, next time you connect to the shell, you should be able to execute the PHP binary directly (assuming your host has provided you with adequate permissions).

For more general tips and tricks for using PHP from the command line, see Replacing Perl Scripts with PHP Scripts, and the PHP Manual on Using PHP from the Command Line.

Running the PEAR Installer

Now you've got the PHP executable in your system path, it's time to fetch and run the PEAR Installer. These days, the Installer is bundled with the PHP distribution, so it's possible that you may already have it on your system. The Installer script is also available from http://pear.php.net/go-pear, and I'll be using this so you know how to install PEAR from scratch.

Windows users, head to http://pear.php.net/go-pear with your browser and simply "Save Page As...". Store it somewhere on your system, for example:

c:\temp\go-pear.php

Now, type:

cd c:\temp  
php go-pear.php

The Installer now starts.

Linux users get an easier life, needing only to type:

$ wget http://pear.php.net/go-pear -O go-pear.php  
$ php go-pear.php

Alternatively, if you have the Lynx text mode browser installed, just type:

$ lynx -source http://pear.php.net/go-pear | php

...which will download and execute the Installer.

Install Options

With the Installer running, you need to answer a few questions about how you'd like the PEAR Package Manager set up. Most of the questions should be straightforward (such as whether you're using proxy server -- the installer talks to the PEAR Website over HTTP).

When it comes to defining the file layout of PEAR, a little thought needs to be undertaken. If you're installing on your own Linux system, it's generally best to accept the default settings (login as root, first). When installing on Windows or on your LAMP host, it's a good idea to change them. These are my preferences, which differ a little from the default settings the Installer provides:

• Option 1 (alias $prefix): Installation Prefix - This a base location under which you can choose to put everything. A good choice might simply be c:\pear on Windows systems. On LAMP, you're probably better off with something like /home/yourname/pear, where "yourname" is the username that you login with (so, you install below your home directory).
• Option 2: Binaries Location - When it says "binaries", it actually means executable PHP scripts, shell scripts and so on. The command line version of the PEAR Package Manager goes here (which is what you're interested in!). This directory will need go to into your systems path variable (using the same procedure as that you used to add the php binary to your path). Generally, a good choice might be $prefix\bin for Windows ($prefix/bin for a LAMP account).
• Option 3 (alias $php_dir): PHP Code Directory - This is the directory under which all the PEAR packages will be placed. It will need to be added to your PHP include_path (more on that in a moment). You might choose $prefix\lib for Windows ($prefix/lib -- LAMP).
• Option 4: Documentation Base Directory - This is where documentation and examples, provided with PEAR packages, will be placed. You'll probably be referring to this directory to see how a package works. On your own development system, you might choose to change this directory to one that's below your Web root directory (e.g. c:\apache\htdocs\pear) so you can quickly view examples with your browser. Be careful, though! Make sure you're not exposing the directory to the world! A safer choice could be $prefix\docs for Windows or $prefix/docs for a Linux hosting account.
• Option 5: Data Base Directory - Some PEAR packages use data stored in, say, XML form, which will be used in some manner by the PHP scripts the package provides (for example, PEAR::Science_Chemistry place a description of water in Chemical Markup Language in the data dir, although purely for testing). A good choice is probably $prefix\data for Windows (or $prefix/data for your LAMP host account).
• Option 6: Test Directory - Place any unit test scripts provided with the package, normally for execution under PEAR::PHPUnit, here. Again, something like $prefix\tests for Windows ($prefix/test -- LAMP).

That's the hard part done. Continue following the prompts and the Installer will download and set up the PEAR Package Manager, along with some extra, commonly used packages, should you choose to accept them (recommended).

Once this is complete, the Installer will attempt to modify your php.ini file, if possible, to add the PEAR library directory (Option 2 above) to your PHP include_path. On your own system, with the correct permission, it will probably get these modifications right. It's a good idea to double check what it does, though, so open up your php.ini (usually in c:\Windows; it varies on Linux) and see that the modifications are correct. Of course, the shared account that your host provides probably won't let you modify php.ini -- workaround coming up!

As I mentioned earlier, PEAR packages are included in your PHP code using the same relative path. So, having the correct include_path is very important (manually modifying PEAR packages is not fun!).

Using the directories I've suggested above, your include_path might look like one of the following:

include_path = ".;c:\pear\lib" ;

…on Windows. Note the semi colon.

include_path = ".:/usr/local/lib/php" ;

…on your own Linux system.

On a shared LAMP host where you have no access to modify php.ini, the best approach is to place a .htaccess file in your Web document root directory (this assumes your host has Apache configured to allow the use of .htaccess files), containing:

php_value "include_path" ".:/home/yourname/pear/lib"

That should apply recursively to subdirectories. If you get internal server errors, it's time to harass your host -- they need to configure Apache for your virtual host to have:

AllowOverride Options

("Options" or "All" should do it.)

If you get desperate, you could also modify your include path in some global script that is already included throughout your application. For example:

<?php  
ini_set("include_path", ".:/home/yourname/pear/lib");

Note that you fetch your existing include path with ini_get(), meaning that you might use the following to preserve the existing include path:

<?php  
$current_path = ini_get("include_path");  
 
// Append a new include path to the existing path  
ini_set("include_path", "$current_path:/home/yourname/pear/lib");

More Environment Changes

Finally, you need to make further modifications to your environment.

Windows users should find a file call PEAR_ENV.reg, placed in the PEAR "binaries" directory by the installer (Option 2 above). This contains instructions that will allow you to edit your registry and create some environment variables that point to the various directories you specified above, so the PEAR Package Manager (and any package needing it) knows how PEAR is set up.

Those on a LAMP host should type:

$ ls -l ~/.pearrc

You should see a file called .pearrc, which PEAR has placed in your home directory. This will be used by the Package Manager to find the directories you specified when running the installer. The content is a serialized PHP array but if you have a look, you should be able to double check that the settings are correct.

The final step is to add the PEAR "binaries" directory to your systems path variable, so you can execute them from anywhere in your directory structure.

Following the steps that you used to add the php binary to your path above, Windows users should append the following (depending on where you installed PEAR):

;c:\pear\bin

Those with LAMP accounts, must edit .profile again, adding:

export PATH=/home/yourname/pear/bin:$PATH

Notice that the $PATH variable goes after the PEAR binaries directory. This is just a precaution, in case your host has its own version of PEAR installed; your version of any PEAR command line scripts should be executed first when you type pear.

That's it! Now you can go on to experiment with the PEAR Package Manager (things get a lot easier from here, I promise).

Other Options

This isn't the only way to set up the PEAR Package Manager. In particular, LAMP account hosts may already have PEAR installed (if you type pear from the command line before doing any of the above, you may see the Package Manager help page). You have the option of "piggy backing" on your host's install, as explained here. Personally, I prefer not to do this as I'm a control freak (at least, I am when it comes to hosting!), but it may make life easier for you to trust your host to know what they're doing with PEAR.

Also, although I'll only be looking at the command line interface here, the PEAR Package Manager has two other "front ends": a Web interface and a PHP-GTK GUI. I've never touched the GTK version, but the Web interface can be useful, especially if you're stuck with a host that gives you no access to the command line (*boo*, *hiss*). There are some notes about setting up the Web front end at PHP Kitchen, which should be easy to adapt to a shared hosting account. Make sure you protect the Web interface with a username/password combination (a .htaccess file should do this for you)!