A.3 Installing PEAR

Many PEAR modules, such as the DB module discussed in Chapter 7, make your PHP programming life easier. They are high-quality code libraries that help you do all sorts of common tasks in PHP programs such as interacting with a database or generating an HTML form. I recommend always having the PEAR libraries available.

Depending on how you have installed PHP (or how your hosting provider has installed PHP), you may need to take extra steps to also install the PEAR base libraries (including DB) and its package management tool. To see whether you have PEAR installed properly, make a short PHP program that just attempts to include DB.php, as shown in Example A-2.

Example A-2. Testing for PEAR installation

require 'DB.php';
if (class_exists('DB')) {
    print "ok";
} else {
    print "failed";
}

If PEAR is installed properly, Example A-2 prints ok. PEAR is not installed correctly if the program prints failed, you get a blank page, or you see an error message like this:

Warning: main(DB.php) [function.main]: failed to open stream:
No such file or directory in /usr/local/apache/htdocs/pearcheck.php on line 2

Fatal error: main( ) [function.require]: Failed opening required 'DB.php'
(include_path='.:/usr/local/php/lib') in /usr/local/apache/htdocs/pearcheck.php
on line 2

The specific steps to take to start the PEAR installation process vary based on your operating system. On Windows, visit http://go-pear.org/ in a web browser and save the contents of that page as C:\PHP\go-pear.org (assuming you've installed PHP in C:\PHP). Then pass that file to the php.exe program. From the command prompt, type:

C:
CD \PHP
PHP go-pear.org

On Linux, as root at a shell prompt, type:

lynx -source go-pear.org | php

On OS X, at a Terminal shell prompt, type:

curl go-pear.org | sudo php

After you've started the PEAR installation process in the appropriate way, the next steps are the same on all platforms. The installation program asks a number of questions about how it should install PEAR. Use the default answers for all the questions, including when it asks you whether it should alter your php.ini file. The installation process must change the include_path setting in php.ini so that require and include work correctly with PEAR libraries.

Once PEAR has been installed successfully, run the PEAR package manager from a command or shell prompt to install and upgrade individual PEAR packages. The package manager is a program called pear. On Windows, you may need to be in the C:\PHP directory to run pear. On Linux, it should work from any directory, but you should be root when you run it. On OS X, you should run sudo pear so that the program has the appropriate permissions.

The OS X PHP package from www.entropy.ch installs its own complete copy of the base PEAR libraries and the PEAR package management tools. Because OS X 10.3.3 comes with a broken PEAR installation, however, you have to distinguish between them. If you just type sudo pear from the Terminal shell prompt, you run the pre-installed tool. To run the version installed with the www.entropy.ch package, you must type sudo /usr/local/php/bin/pear. To save yourself some typing, you can overwrite the preinstalled pear tool with the following:

sudo cp /usr/local/php/bin/pear /usr/bin/pear

Then, you can just type sudo pear at the Terminal shell prompt to access the right version of the package management tool.

The pear program understands a number of commands that control its behavior. You can see a list of them by running it with no additional arguments. The three most useful commands are list, which shows you what packages you have installed, install, which installs a new package, and uninstall, which removes an installed package.

For example, to list installed packages, type pear list. This prints a list of installed packages and their versions:

INSTALLED PACKAGES:
= = = = = = = = = = = = =
PACKAGE        VERSION STATE
Archive_Tar    1.1     stable
Console_Getopt 1.2     stable
DB             1.6.2   stable
Mail           1.1.3   stable
Net_SMTP       1.2.6   stable
Net_Socket     1.0.1   stable
PEAR           1.3.1   stable
PHPUnit        1.0.1   stable
XML_Parser     1.1.0   stable
XML_RPC        1.1.0   stable

To install a package, type pear install. It's a good idea to use the -a flag with install so that any packages required by the package you're trying to install are also installed. For example, to install the HTML_QuickForm package discussed in Section 13.7, type:

pear install -a HTML_QuickForm

The HTML_QuickForm package requires the HTML_Common package, so both are downloaded and installed. The pear program prints:

downloading HTML_QuickForm-3.2.2.tgz ...
Starting to download HTML_QuickForm-3.2.2.tgz (88,941 bytes)
.....................done: 88,941 bytes
downloading HTML_Common-1.2.1.tgz ...
Starting to download HTML_Common-1.2.1.tgz (3,637 bytes)
...done: 3,637 bytes
install ok: HTML_Common 1.2.1
install ok: HTML_QuickForm 3.2.2

To remove a package, use pear uninstall. For example, to remove HTML_QuickForm and HTML_Common, you must run pear uninstall twice. First, uninstall HTML_QuickForm:

pear uninstall HTML_QuickForm

This prints:

uninstall ok: HTML_QuickForm

Then, uninstall HTML_Common:

pear uninstall HTML_Common

This prints:

uninstall ok: HTML_Common

HTML_QuickForm must be uninstalled before HTML_Common because HTML_QuickForm depends on HTML_Common. If you try to remove HTML_Common first, you get this error message:

Package 'html_quickform' depends on 'HTML_Common'
uninstall failed