How do I install PEAR?

The PHP Extension and Application Repository, or "PEAR", is a repository of reusable PHP code which you can add to your website to easily enable certain functions such as SMTP Mail.

Various packages can be downloaded from the PEAR repository, at:

• pear.php.net/packages.php

The following information walks you through the following:

• How to set up your DreamHost environment to run PEAR.
• How to download and install the packages.

Both PEAR MAIL and PHPMailer allow you to send email using SMTP. But there are a few reasons why PHPMailer may be a better choice. For example:

• PEAR MAIL cycles the socket connection for each message. This could potentially cause the connection to be caught by DreamHost's servers as a brute force attempt.
• PHPMailer open a socket only once. The socket is then kept open as it processes messages.
• PHPMailer is very well documented with many online examples and help pages.
• PHPMailer integrates well with Google's SMTP servers.

For these reasons, PHPMailer is worth taking a look at as an alternative to PEAR MAIL.

1. Make sure the user assigned to your domain is a SHELL user. Visit the following article which explains how to set up your SHELL user:
   • Creating a user with Shell (SSH) access
2. Once the user is a SHELL user, log into the web server via SSH. Visit the SSH article for instructions on how to log into your server depending on which operating system you are using:
   • SSH overview
3. Once you’ve logged into your server, make sure you're in your user's directory. Run these commands in your SHELL terminal:

   [server]$ cd ~
   [server]$ pwd 
   /home/username

   • User is named username.
   • In this example, you can see you're in the user's directory because the full path is /home/username.
4. Make a temporary directory. This will be used in the following steps when installing.

   [server]$ mkdir -p pear/tmp/pear/install

5. Run the following wget command to download the go-pear.phar file to your user's directory:

   [server]$ wget https://pear.php.net/go-pear.phar

6. Run the file by entering this command in the same directory:

   [server]$ /usr/local/php74/bin/php go-pear.phar

7. During the install process, provide the following responses at the prompts:

   [server]$ /usr/local/php74/bin/php go-pear.phar
   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 base ($prefix)                   : /home/username/pear
    2. Temporary directory for processing            : /tmp/pear/install
    3. Temporary directory for downloads             : /tmp/pear/install
    4. Binaries directory                            : /home/username/pear/bin
    5. PHP code directory ($php_dir)                 : /home/username/pear/share/pear
    6. Documentation directory                       : /home/username/pear/docs
    7. Data directory                                : /home/username/pear/data
    8. User-modifiable configuration files directory : /home/username/pear/cfg
    9. Public Web Files directory                    : /home/username/pear/www
   10. Tests directory                               : /home/username/pear/tests
   11. Name of configuration file                    : /home/username/.pearrc
   
   1-11, 'all' or Enter to continue:
   

8. You should change the location of the tmp directories. Type 2 and press Enter.

   (Use $prefix as a shortcut for '/home/username/pear', etc.)
   Temporary directory for processing [/tmp/pear/install] : /home/username/pear/tmp/pear/install

   Change the username to your actual Shell username in the command above.
9. Press Enter to save and proceed.
10. The list appears again. This type 3 and press Enter.

    (Use $prefix as a shortcut for '/home/username/pear', etc.)
    Temporary directory for downloads [/tmp/pear/install] : /home/username/pear/tmp/pear/install

    Change the username to your actual Shell username in the command above.
11. Click Enter to save and proceed.

    WARNING!  The include_path defined in the currently used php.ini does not
    contain the PEAR PHP directory you just specified:
    </home/username/pear/share/pear>
    If the specified directory is also not in the include_path used by
    your scripts, you will have problems getting any PEAR packages working.
    
    Would you like to alter php.ini </etc/php74/php.ini>? [Y/n] :

12. Type in Y and press Enter.

    WARNING: Cannot write to /etc/php74/php.ini, but php.ini was successfully created
    at </home/username/pear/php.ini-gopear>. Please replace the file </etc/php74/php.ini> with
    </home/username/pear/php.ini-gopear> or modify your php.ini by adding:
    
    include_path=".:/home/username/pear/share/pear"
    
    Current include path           : .:
    Configured directory           : /home/username/pear/share/pear
    Currently used php.ini (guess) : /etc/php74/php.ini
    Press Enter to continue:

13. Click Enter again to proceed.

    The 'pear' command is now at your service at /home/username/pear/bin/pear
    
    ** The 'pear' command is not currently in your PATH, so you need to
    ** use '/home/username/pear/bin/pear' until you have added
    ** '/home/username/pear/bin' to your PATH environment variable.
    
    Run it without parameters to see the available actions, try 'pear list'
    to see what packages are installed, or 'pear help' for help.
    
    For more information about PEAR, see:
    
      http://pear.php.net/faq.php
      http://pear.php.net/manual/
    
    Thanks for using go-pear!

    The include_path will be set in the following steps.
14. View the creating and editing a file via SSH article for instructions on how to edit your existing .bash_profile. You’ll see these lines already in that file:

    # ~/.bash_profile: executed by bash(1) for login shells. 
    
    umask 002 
    PS1='[\h]$ '

15. At the bottom, enter these two lines:

    export PHP_PEAR_PHP_BIN=/usr/local/php74/bin/php
    export PATH=${HOME}/pear/bin:/usr/local/php74/bin:${PATH}

16. Save and close the file and return to your shell.
17. Run the following command to allow your current Shell session to use PEAR:

    [server]$ . ~/.bash_profile

You've now installed PEAR – but for your environment to know where to find this installation, you must set up the include_path within your phprc file.

1. Update your phprc file to allow PHP to know where to look for the PEAR install. View the following articles for instructions on how to create a phprc file.
   • How do I create a phprc file via SSH?
   If the file already exists, view the following article for instructions on how to update it:
   • Creating and editing a file via SSH
2. Update the phprc file with the following command:

   include_path = ".:/home/username/pear/share/pear"

   • Change username to your actual Shell username that the domain is under.
3. Navigate back to your user's directory.

   [server]$ cd ~

4. Once there, run pear list to see if you get a response:

   [server]$ pear list
   
   Installed packages, channel pear.php.net:
   Package          Version State
   Archive_Tar      1.3.12  stable
   Console_Getopt   1.3.1   stable
   PEAR             1.9.5   stable
   Structures_Graph 1.0.4   stable
   XML_Util         1.2.3   stable
   

Since you receive a response, you can see that PEAR is now functioning.

When you installed PEAR above, you manually set the location of the tmp directories. You should also update the location of the cache directory to this temp location.

Run the following to view the current /tmp directories:

[server]$ pear config-show | grep cache_dir
PEAR Installer cache directory cache_dir        /tmp/pear/cache

Run the following to update the cache tmp directory. Change username to the shell user you're currently running the command under.

[server]$ pear config-set cache_dir /home/username/pear/tmp/
config-set succeeded

You are now able to install any packages you like using the pear command. For example, run the following to install the mail package:

[server]$ pear install --alldeps Mail

• The -onlyreqdeps flag instructs the installer to install only required dependencies.
• Visit pear.php.net/packages.php for a list of available packages.

If you see any errors when attempting to install, view the following article for possible solutions:

• Troubleshooting PEAR errors

Confirming your PEAR environment settings

[server]$ which php

[server]$ php -v

[server]$ which pear

[server]$ pear -V

[server]$ pear config-show

Troubleshooting

Example of a PHP SMTP mail script

See also