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:

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. Run the following wget command to download the go-pear.phar file to your users directory:
    [server]$ wget http://pear.php.net/go-pear.phar
    --2015-01-26 10:27:03-- http://pear.php.net/go-pear.phar
    Resolving pear.php.net (pear.php.net)... 5.77.39.20
    Connecting to pear.php.net (pear.php.net)|5.77.39.20|:80... connected.
    HTTP request sent, awaiting response... 200 OK
    Length: 3673193 (3.5M) [application/octet-stream]
    Saving to: `go-pear.phar' 

    100%[=====================>] 3,673,193 1.26M/s in 2.8s 2015-01-26 10:27:06 (1.26 MB/s) - `go-pear.phar' saved [3673193/3673193]
  5. Run the file by entering this command in the same directory:
    [server]$ /usr/local/php56/bin/php go-pear.phar
  6. During the install process, provide the following responses at the prompts:
    [server]$ /usr/local/php56/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:
    
  7. Click Enter on your keyboard to proceed with the installation.

    You can alter these later by editing your .pearrc file in your users directory.

    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/php56/php.ini>? [Y/n] : n
    
  8. 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/php56/php.ini
    Press Enter to continue:
    
  9. Click Enter again on your keyboard. The include path will be set in the following steps.
  10. 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]$ '
  11. At the bottom, enter these two lines:
    export PHP_PEAR_PHP_BIN=/usr/local/php56/bin/php
    export PATH=${HOME}/pear/bin:/usr/local/php56/bin:${PATH}
  12. Save and close the file and return to your shell.
  13. 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 directory pear uses

When you install pear, it uses the server's /tmp directory. On a shared server, this may cause the installation of packages to fail.

To avoid this issue, make sure to adjust three configuration options in your pear config. For example, 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     /tmp/pear/install
PEAR Installer temp directory  temp_dir         /tmp/pear/install

You must update those three settings. First, create a /tmp directory in your user's directory:

[server]$ cd ~
[server]$ mkdir tmp

Then update the three configuration options. In these examples, change 'username' to the shell user you're currently running the commands under.

[server]$ pear config-set cache_dir /home/username/tmp
config-set succeeded
[server]$ pear config-set download_dir /home/username/tmp
config-set succeeded
[server]$ pear config-set temp_dir /home/username/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 --onlyreqdeps Mail

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

PEAR channel server

One reason DreamHost users might want to install their own local version of PEAR is to provide themselves with the infrastructure to host a PEAR channel. For details on how to install a PEAR channel server, read the official instructions

  • Alternatively, you can consider using Pirum

Troubleshooting

View the following article for troubleshooting examples:

See also

Internal links

External links

Did this article answer your questions?

Article last updated .