Details:

Pear is pre-installed and available for use on (gs) Grid-Services. The path to Pear is '/usr/local/php-x.x.x-x/share/pear' where php-x.x.x-x is replaced by the version of php that is active on your site. The installation directories have already been added to your include_path so nothing special is needed to use our preinstalled Pear modules. The list of preinstalled modules is as follows:

Package Version State
Archive_Tar 1.3.1 stable
Console_Getopt 1.2 stable
HTML_Template_IT 1.1 stable
Net_UserAgent_Detect 2.0.1 stable
PEAR 1.4.9 stable

Installing custom Pear packages

Some developers may want to install Pear packages that we have not included. Due to the nature of grid hosting there are a few caveats involved in getting Pear modules installed on the Grid. To install a new Pear package on your (gs) Grid-Service:

1. Log into your (gs) via SSH as 'serveradmin@mt-example.com'. For help with SSH please see our KB article - Connecting via SSH to your (gs) Grid-Service
   
2. To install custom Pear packages you must do a complete Pear installation in your home directory. Start by telling the global version of Pear to generate a configuration file for your home directory.  We will also run a few other commands to set up your Pear environment:
   

   /usr/local/pear/bin/pear config-create $PWD .pearrc
   /usr/local/pear/bin/pear config-set download_dir /home/#####/users/.home/pear/download
   /usr/local/pear/bin/pear config-set cache_dir /home/#####/users/.home/pear/cache
   

3. Now we'll tell the global version of Pear to install another version in your home directory so your user can have write access:
   

   /usr/local/pear/bin/pear install -o PEAR

4. Let's add the path to your new Pear installation to your bash_profile so you won't have to type the full path anymore. Open or create a file in your home directory named '.bash_profile' and add the following line:
   

   export PATH=/home/#####/users/.home/pear/:$PATH

   Please remember to substitute your site number for the '#####' symbols. 
5. Set the Download Directory:
   

   pear config-set download_dir /path/to/folder

6. Now you may install any Pear packages you like with the 'pear' command. As an example let's install the newest Mail package:
   

   pear install -o Mail

Now that Pear is installed locally you must alter your include_path so your scripts know where to look for the new packages. There are three ways to do this:

1. Globally: edit your custom php.ini to include the new path to pear. This change will affect all scripts on your site. Simply add a line that reads:
   

   include_path = ".:/home/#####/users/.home/pear/php"

   Please be sure to substitute your actual site number for the '#####' symbols. For more help with editing your php.ini please see our KB article - How can I edit php.ini on the (gs) Grid-Service?
   
2. On a per directory basis -- Using an .htaccess file to change your include_path for all php scripts in a single directory. This change does not affect scripts outside of this directory. Create an .htaccess file in the desired directory and add the following line:
   

   php_value include_path '/home/#####/users/.home/pear/php'

   Please be sure to substitute your actual site number for the '#####' symbols. For more help with creating .htaccess files please see our KB article - Using .htaccess files
   
3. For a single script -- This change will only work for the script. Edit your script and add the following line near the top:
   

   set_include_path('/home/#####/users/.home/pear/php');

   Please be sure to substitute your actual site number for the '#####' symbols.

export PATH="/home/#####/users/.home/pear/:/usr/local/php-5.2.6-1/bin:$PATH"

Revisions:

09-23-2009: Corrected several commands
09-21-2009: Corrected links and added additional pear commands to set up environment properly.
08-21-2009: Fixed site number reference for the note. Thanks Victor!
07-20-2009: Minor Fixes