Tutorials > PEAR > Starting Out

The first thing we need to do is to determine which version of PHP you have installed on your web server. If you're running PHP > 4.3 then PEAR was installed when you built PHP. However, if you built PHP with the ’--disable-cli’ option PEAR was not installed.

The easiest way to determine which version of PHP you're running, and the configuration options used during the build, is to create a PHP file with the following line of code:

<?php phpinfo(); ?>

Next, open a web browser and navigate to the file you just created. When the page loads you should see your PHP Info page. Check the version number and configure command. If you're running PHP > 4.3 and did not use the ’--disable-cli’ configuration option then PEAR should be installed.

One more test is to type ’pear’ at the command prompt on your web server. If you see a list of PEAR commands then PEAR is installed. You can skip ahead to the Basic PEAR Commands.

2.1 Installing PEAR

OK, if you're on this step then PEAR is not installed on your web server. The easiest way to install PEAR is to upgrade to PHP > 4.3, but that may not be an option. Luckily the folks at PEAR made installation extreemly easy. Open a shell to your web server and run the following command:

% lynx -source http://go-pear.org | php -q

This command will download the PEAR installation script (a PHP script, go figure) from the PEAR website and run it through the command line version of PHP. If everything went well you will see a message like this:

Welcome to go-pear!

Go-pear will install the 'pear' command and all the files needed by
it.  This command is your tool for PEAR installation and maintenance.

Go-pear also lets you download and install the PEAR packages bundled
with PHP: DB, Net_Socket, Net_SMTP, Mail, XML_Parser, PHPUnit.

If you wish to abort, press Control-C now, or press Enter to continue:

Next you will be prompted for an HTTP Proxy.

HTTP proxy (http://user:password@proxy.myhost.com:port), or Enter for none:

Once PHP establishes a connection with the PEAR website you will be given the option to configure your PEAR installation.

Below is a suggested file layout for your new PEAR installation.  To
change individual locations, type the number in front of the
directory.  Type 'all' to change all of them or simply press Enter to
accept these locations.

 1. Installation prefix           : /usr/local
 2. Binaries directory            : $prefix/bin
 3. PHP code directory ($php_dir) : $prefix/lib/php
 4. Documentation base directory  : $php_dir/docs
 5. Data base directory           : $php_dir/data
 6. Tests base directory          : $php_dir/tests

1-6, 'all' or Enter to continue:

Modify these options according to your PHP installation. One thing to keep in mind is the PEAR installation will need to write files and directories according to the list above. If you are running the installation process as a user that does not have write privs to the nexessary directories the installation will fail.

If you've made it through the stp above you will see the following message:

The following PEAR packages are bundled with PHP: DB, Net_Socket, Net_SMTP,
Mail, XML_Parser, PHPUnit.
Would you like to install these as well? [Y/n] :

I suggest installing all of the bundled packages for a couple reasons. First, they are extremely usefull. Second, certain PEAR pagakages depend on other packages. The packages above can be considdered "core" packages as other PEAR modules use them.

Once you decide which pacakges to install PHP will download the necessary files and install them. When your installation is complete you should see the following message:

The 'pear' command is now at your service at /usr/local/bin/pear

Believe it or not, this is all you need to do to install PEAR.

2.2 Basic PEAR Commands

So, is your PEAR installation running? Let's get to know PEAR a bit better by looking at your current configuration. To run a pear command simply type

% pear command

% pear config-show

% pear config-help

% pear config-set option value

2.3 Adding New Packages

Often you will want to use a PEAR package that did not come bundled with PEAR. In this case you will need to install the package. The first step is to check which packages are already installed. Type:

% pear list

You should see a list of all the PEAR packages installed, the version and their current state. Let's install the PEAR package used to parse an RSS news feed (if you don't know what that is, it's just an XML file).

First we need to identify the package we need to install. This can be done two ways. First, you can check the PEAR website package list or you can type:

% pear list-all

Both have advantages and disadvtages. Using the PEAR website the packages are organized by category, which is handy. The command line interface not only shows you which packages are available but also the version you have installed on your machine. Eaither way you will get a list of all the packages available. We're looking for XML_RSS.

Let's get a little information about this package. Type:

% pear remote-info XML_RSS

This command will contact the PEAR server and get the vital information for the XML_RSS package. You should see the following information.

Package details:
================
Latest      0.9.2
Installed   - no -
Package     XML_RSS
License     PHP License
Category    XML
Summary     RSS parser
Description Parser for Resource Description Framework (RDF)
            Site Summary (RSS)
            documents.

Everyhing looks good. Let's go ahead and install the package.

% pear install XML_RSS
downloading XML_RSS-0.9.2.tgz ...
Starting to download XML_RSS-0.9.2.tgz (3,515 bytes)
....done: 3,515 bytes
requires package `XML_Tree'
XML_RSS: Dependencies failed

Did it work. Nope. According to the message above PEAR downloaded the package but when it dried to install it it failed a dependency check. The PEAR XML_RSS package depends on the XML_Tree package. Don't get caught up in the different package names. Esentially code in the package we want to install relies on the code in some other package we don't know about. We don't know how they depend on each other, but they do. In order to install the our package we must install all packages that it depends on. The easiest way to do this is use the same install command we used above and list all the packages.

% pear install XML_Tree XML_RSS

You should see some data flash accross the screen. Most of it is confirmation that PEAR is downloading and installing the sepcified packages. In our case you want to look for the following two lines:

install ok: XML_Tree 1.1
install ok: XML_RSS 0.9.2

This specifies that our modules were installed successfully. Next I'll show you how to utilize a PEAR package in your code.