How do I install PEAR?

Overview

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:

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.

PEAR MAIL compared to PHPMailer

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.

Installing PEAR manually

PEAR is not installed by default on DreamHost servers. If you require any PEAR package to operate on your site it must be installed manually using the following steps.

  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:
  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:
  3. Once you’ve logged into your server, make sure you're in your users directory. Run this command in your SHELL terminal:
    [server]$ pwd 
    /home/exampleuser
    • User is named ‘exampleuser’.
    • In this example, you can see you're in the users directory because the full path is /home/exampleuser.
  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 users directory:
    [server]$ wget https://objects-us-east-1.dream.io/kbfiles/pear/go-pear.phar --no-check-certificate
  6. Run the file by entering this command in the same directory:
    [server]$ /usr/local/php72/bin/php go-pear.phar
  7. During the install process, provide the following responses at the prompts:
    [server]$ /usr/local/php72/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/exampleuser/pear
     2. Temporary directory for processing            : /tmp/pear/install
     3. Temporary directory for downloads             : /tmp/pear/install
     4. Binaries directory                            : /home/exampleuser/pear/bin
     5. PHP code directory ($php_dir)                 : /home/exampleuser/pear/share/pear
     6. Documentation directory                       : /home/exampleuser/pear/docs
     7. Data directory                                : /home/exampleuser/pear/data
     8. User-modifiable configuration files directory : /home/exampleuser/pear/cfg
     9. Public Web Files directory                    : /home/exampleuser/pear/www
    10. Tests directory                               : /home/exampleuser/pear/tests
    11. Name of configuration file                    : /home/exampleuser/.pearrc
    
    1-11, 'all' or Enter to continue:
    
  8. You should change the location of the tmp directories. Type 2 and click 'Enter'.
    (Use $prefix as a shortcut for '/home/exampleuser/pear', etc.)
    Temporary directory for processing [/tmp/pear/install] : /home/exampleuser/pear/tmp/pear/install
    Change the 'exampleuser' to your actual Shell username in the command above.
  9. Click 'Enter' to save and proceed.
  10. The list appears again. This type type 3 and click 'Enter'.
    (Use $prefix as a shortcut for '/home/exampleuser/pear', etc.)
    Temporary directory for downloads [/tmp/pear/install] : /home/exampleuser/pear/tmp/pear/install
    Change the 'exampleuser' to your actual Shell username in the command above.
  11. Click 'Enter' to save and proceed.
  12. Click 'Enter' again to proceed.
    The install will continue to run, but then stops at this question:
    WARNING! The include_path defined in the currently used php.ini does not
    contain the PEAR PHP directory you just specified:
    </home/exampleuser/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/php72/php.ini>? [Y/n] : n
    
  13. Enter the letter ‘n’ and then click Enter to proceed with the install. You will be able to set the include path in the next few steps.
    You’ll finally see this last section of the install script:
    I will add a workaround for this in the 'pear' command to make sure the installer works, 
    but please look over your php.ini or Apache configuration to make sure /home/exampleuser/pear/share/pear 
    is in your include_path.
    
    Current include path           : .:/usr/local/lib/php:/usr/local/php5/lib/pear
    Configured directory           : /home/exampleuser/pear/share/pear
    Currently used php.ini (guess) : /etc/php72/php.ini
    Press Enter to continue:
    
  14. Click Enter again on your keyboard. The include path will be set in the following steps.
  15. 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]$ '
  16. At the bottom, enter these two lines:
    export PHP_PEAR_PHP_BIN=/usr/local/php72/bin/php
    export PATH=${HOME}/pear/bin:/usr/local/php72/bin:${PATH}
  17. Save and close the file and return to your shell.
  18. 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.

Setting the include_path in your phprc file

If you do not set up this include_path correctly, you may find your installation does not work as intended.

  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. If the file already exists, view the following article for instructions on how to update it:
  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 users 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.

Changing the /tmp cache directory

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 tmp
PEAR Installer cache directory cache_dir        /tmp/pear/cache
PEAR Installer download        download_dir     /home/exampleuser/pear/tmp/pear/install
PEAR Installer temp directory  temp_dir         /home/exampleuser/pear/tmp/pear/install

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/exampleuser/pear/tmp/
config-set succeeded

Installing packages

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 http://pear.php.net/packages.php for a list of available packages.

Confirming your PEAR environment settings

To see if your environment is correctly set, run the following commands in your users directory:

To determine which PHP (local or shared) command will be used:

[server]$ which php

To determine which PHP version is being used:

[server]$ php -v

To determine which PEAR (local or shared) command will be used:

[server]$ which pear

To determine which PEAR version is being used:

[server]$ pear -V

Use this command to display all your PEAR settings – your local configuration data should display:

[server]$ pear config-show

Troubleshooting

View the following article for troubleshooting examples:

Example of a PHP SMTP mail script

View the following article for an example of how to send PHP mail via SMTP.

See also

Did this article answer your questions?

Article last updated PST.