Site5 - Built For Designers & Developers MENU

How To Setup Your Own PHP PEAR Environment


We regularly receive requests for PEAR library installations, so I thought it would be a good idea to explain how to setup your own PEAR environment ( so you can install the libraries yourself inside your home directory.

In this tutorial, I will be using the $HOME environment variable to represent the home directory (/home/user). The $HOME variable will work in the shell, so most of the commands I show (unless stated otherwise) can simply be copy and pasted into your own shell. You may alternatively use the tilde (~) to represent your home directory, that choice is up to you.

To begin, if you have already attempted to configure your own PEAR environment, please make sure to revert your modifications. Specifically, remove the $HOME/pear directory and the $HOME/.pearrc file, if they exist (WARNING: this will remove any libraries you may already have installed).

The first step you need to take is logging in to the server via SSH. Once logged in, you will see a prompt similar to the one below:

[user@servername ~]$

To confirm that you are using our version of PEAR and not any locally installed versions, please type the following command:

which pear

If it returns anything that starts with “/home/” you have not correctly reverted your changes. Please go back through your account and make sure everything has been reverted. You may simply need to run a “source ~/.bash_profile” to pickup the changes or logout and then log back in to your SSH session. If everything is configured properly, the “which pear” command should return the following:


The first command you need to run is the PEAR configuration file creator. Run the command exactly as shown below:

pear config-create $HOME $HOME/.pearrc

This command will output a large amount of data showing you where PEAR will be configured to store its various files and directories. It also writes the “.pearrc” file to your home directory. By default, PEAR will keep all binaries installed with PEAR in the main PEAR directory. Some people would rather these be stored in a separate directory ($HOME/bin), so I will show you how to make this change. Simply run the following command:

pear config-set bin_dir $HOME/bin

Any binaries installed through PEAR will now be installed in the $HOME/bin directory. After that command is run, you will be presented with a “config-set succeeded” message confirming that it was successful. At this point, you need to take note of two configuration values in PEAR, the bin_dir and the php_dir. To get these values, run both of the following commands:

For “bin_dir”:
pear config-show | grep bin_dir | awk '{print $5}'

For “php_dir”:
pear config-show | grep php_dir | awk '{print $4}'

We will use both of these later, so make sure to save them somewhere.

You should now be able to install some PEAR libraries. Let’s try to install one called XML_Parser. Run the following command:

pear install XML_Parser

You should see the following output towards the end, which indicates a successful install:

install ok: channel://

Now that PEAR is configured, the next step is ensuring that these libraries are recognized by PHP. By default, PHP only looks in system directories, so you need to make the changes below in order for PHP to see the PEAR libraries you have installed.

First, go to the directory where you are installing your PHP script. If your PHP script is in the public_html directory, you would type “cd $HOME/public_html” at the prompt and hit enter. You then need to copy the default php.ini file into this directory with the following command:

cp /usr/local/lib/php.ini .

(the period at the end is important, don’t forget to include it)

After the file has been copied, open the file in your favorite command line text editor (vim, pico, or nano) and find the “include_path” line. It will look like this:

include_path = ".:/usr/lib/php:/usr/local/lib/php"

Note: If you are not comfortable using a command line editor, you can download the file to your computer, make the changes, and then re-upload the file to the server (overwriting the original).

You need to modify the “include_path” line by adding the php_dir path we retrieved earlier. To add it, simply append a colon (:) after /usr/local/lib/php and add the path you retrieved earlier with the “pear config-show” command for php_dir. The final result should look something like this:

include_path = ".:/usr/lib/php:/usr/local/lib/php:/home/username/pear/php"

(username needs to be your actual user name)

Close that file and save the changes you made. The php.ini file you have created can now be used inside any directory on your account. Remember, if you have another PHP script in a sub-directory that requires any PEAR libraries, you need to copy the modified php.ini file into that directory also.

Your account should now be all set to use PEAR. If you install any PEAR libraries that include binaries (symfony, for example), you may simply call them via the binary name as they will be installed in $HOME/bin. Our default .bash_profile adds the $HOME/bin path to your $PATH environment variable, which is why this works.

Please remember that some PEAR libraries are not in the default PEAR channel and you must do a “pear channel-discover” on the third party channel in order for PEAR to find the requested library.

If you have any questions about this process or if anything is unclear, please leave a note in the comments and I’ll answer it to the best of my knowledge.