Installation of a local PEAR copy on a shared host

Many users have a shared provider that grants access to a system-wide PEAR installation. However, in many cases, it is advantageous to have a local copy of PEAR that can be used for packages that are not installed by the host provider. There are ways of installing PEAR both for users with a telnet/ssh shell access and users who only have ftp access.

Installing a local copy of PEAR through SSH

To install PEAR through SSH, you can use this command sequence to set up a local copy of PEAR:

The following instructions are for PEAR 1.4+, older pear installations should be upgraded immediately.

      
$ pear config-create /home/user/pear .pearrc
      
     

This will create a local configuration file in a file in your home directory named .pearrc.

Then, if you add ~/pear/bin to your path as the first entry in .bashrc (or whatever your startup file is), and run the command:

      
$ pear install -o PEAR
      
     

This will create a directory structure based on a subdirectory of your home directory named pear that contains all of the packages that you install. You will have a local version of PEAR that supersedes the system's copy. To use the files you have installed, you should set your PHP include_path in either the code that uses your PEAR packages like so:

<?php
ini_set
('include_path''~/pear/lib' PATH_SEPARATOR
        
ini_get('include_path'));

// From PHP 4.3.0 onward, you can use the following,
// which especially useful on shared hosts:
set_include_path('~/pear/lib' PATH_SEPARATOR
                 
get_include_path());
?>

Or, in an .htaccess file for apache using php_value.

Installing a local copy of PEAR through ftp/ftps/sftp

There are two ways to install a local copy of PEAR through ftp: the old, difficult way, and the new, easy way. The new, easy way requires an upgrade to version 1.4.3 or newer of PEAR.

New improved method using PEAR 1.4.3+ and PEAR_RemoteInstaller

Installing a local copy of PEAR through ftp has become a piece of cake in PEAR 1.4.3+.

One of the banes of many user's existence is trying to install PEAR on a remote host that does not have shell access. Often, the only choice is to use FTP, but even this is a problem for more complex packages that take advantage of installer features like replacements.

Here is the sequence necessary to get things running:

  1. Make sure you are running PHP 5.0 or newer on your local computer

  2. If you wish to use ftps, make sure you have enabled the openssl extension on your local computer in php.ini.

  3. If you wish to use sftp, make sure you have enabled the ssh2 extension on your local computer in php.ini.

  4. Make sure you have a working copy of the CLI version of PEAR on your local computer (the "pear" command, not the web interface)

  5. Make sure you have ftp access to the remote host, and write access through ftp. (sftp or ftps is highly recommended for security reasons).

  6. Note the full path to your home directory

  7. Create a customized configuration file for both the local and remote host

  8. Upload the remote configuration file to the remote host

  9. Using the local configuration file, set the remote_config value to the location of the configuration file on the remote host

  10. Manage packages at will using the remote-install, remote-uninstall, remote-upgrade and remote-upgrade-all commands.

1. Make sure you have a working copy of the CLI version of PEAR (the "pear" command, not the web interface)

Read The installation instructions.

2. Install package PEAR_RemoteInstaller locally if not already done.

3. Make sure you have ftp access to the remote host, and write access through ftp

This is pretty straightforward - if you can login using the ftp command in a DOS prompt or from a unix shell, you have ftp access.

Write down the user and password that you need to login.

Testing write access is easy. If you can upload a file, you have write access.

4. Note the full path to your home directory

This is also pretty straightforward. Upload this script to the root directory of your web host to find out:


<?php
echo dirname(__FILE__);
?>

Chances are, it will be something like: /home/username/htdocs or /home/username/public_html. When you log into ftp, if you can change directory to /home/username, that's great.

5. create a customized config file for both the local and the remote host

This is also quite simple. Here is how to do this on windows and unix.

Windows first:

Pick a location to store your local copy of the remote code. For example, C:\remote\pear. From a Command prompt (click Start here => Programs and search for the Command Prompt), type:

       
C:\> mkdir remote
C:\> cd remote
C:\remote\> mkdir pear
C:\remote\> cd pear
C:\remote\pear> pear config-create -w C:\remote\pear remote.ini
C:\remote\pear> pear config-create /home/username/pear .pearrc
       

In Unix, follow a similar process:

       
$ cd
$ mkdir remote
$ cd remote
$ mkdir pear
$ cd pear
$ pear config-create /home/mylocaluser remote.conf
$ pear config-create /home/username/pear .pearrc
       

6. upload the remote configuration file to the remote host

This is straightforward - in both operating systems, use ftp to upload .pearrc to /home/username/pear/.pearrc

7. using the local configuration file, set the remote_config value to the location of the configuration file on the remote host

If you wish to use unencrypted ftp (remember: this is inherently insecure), then use ftp:// as your stream. If you wish to use ftps, then use ftps:// as your stream. If you wish to use sftp, then use ssh2.sftp as your stream.

The path you use for the remote_config variable may need to be a full pathname, as in:

       
ssh2.sftp://user:pass@myremotehost.com/home/username/.pearrc
       

If the initial connection attempt fails, try a relative path as in:

       
ftps://user:pass@myremotehost.com/.pearrc
       

To set the value of the remote_config configuration variable, use this syntax:

In windows:

       
C:\remote\pear\> pear -c remote.ini config-set remote_config \
    ftp://user:pass@myremotehost.com/.pearrc
       

In Unix:

       
$ pear -c remote.conf config-set remote_config \
    ftp://user:pass@myremotehost.com/.pearrc
       

8. Manage packages at will using the remote-install, remote-uninstall, remote-upgrade and remote-upgrade-all commands.

From this point on, you can synchronize the local and the remote repositories.

How does it work?

The installer installs the package locally, and then uses ftp streams and uploads a copy of each locally installed file to its equivalent location remotely. All commands that affect installation (install, uninstall, upgrade, and upgrade-all) have corresponding remote- commands (remote-install, remote-uninstall, remote-upgrade, remote-upgrade-all). The "remote_config" option tells the installer how to retrieve the remote configuration file containing absolute paths where packages should be installed.

The remote configuration file is used for any special tasks such as replacements. In other words, if a file expects to get the path to data files through the data_dir configuration directive, then it will have the path on the remote host (/home/username/pear/data) rather than the local copy ( C:\remote\pear\data). Note that packages installed this way will not work on the local machine, and should be thought of as a backup copy. In an emergency, you can always just upload the entire contents to the remote host using ftp or scp.

It is important to note that some packages install themselves differently on windows and on unix. Be sure you know whether this is the case before installing, or ensure that your local and remote systems are the same kind of operating system. In addition, your local packages may depend on PHP extensions. To ensure these are available on the remote server, use the output of phpinfo(); to determine which extensions are available.

The traditional way of installing a local copy of PEAR through ftp

In order to install a local copy of PEAR through ftp, you must have an ftp client that can set permissions on upload. First, create a directory that is NOT in your publicly accessible web space, and name it anything you'd like. Set it to be readable and writable by any user (permissions 0777). Then, download a copy of http://pear.php.net/go-pear.phar and save it as go-pear.php. Upload go-pear.php to a subdirectory of your publicly accessible web space. It is a very good idea to password-protect the directory containing go-pear.php with an .htaccess file.

Next, browse to the go-pear.php file. If your web address is http://www.example.com/, you have placed go-pear.php in public_html/install/go-pear.php, and http://www.example.com/ will browse to public_html/, then browse to http://www.example.com/install/go-pear.php. Follow the installation prompts. When asked where to install PEAR, choose the directory you created to be readable and writable by any user. You will need to know the location of the cli version of PHP. To find this, browse to this script and copy the output:

<?php
echo `which php`;
// if this does not work, also try echo PHP_BIN;
?>

After PEAR has been installed, you can use the web installer to install and upgrade packages just as you would with any other PEAR installation. To use the files, you must set the include path in scripts on the website.

<?php
ini_set
('include_path''~/pear/lib' PATH_SEPARATOR
        
ini_get('include_path'));

// From PHP 4.3.0 onward, you can use the following,
// which especially useful on shared hosts:
set_include_path('~/pear/lib' PATH_SEPARATOR
                 
get_include_path());
?>
Getting and installing the PEAR package manager (Previous) Checking if PEAR works (Next)
Last updated: Thu, 24 Apr 2014 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by: barbs
I get 'config-set: only the layers: "user" or "system" are supported' when running the command "pear -c remote.ini config-set remote_config \ ftp://user:pass@myhost.com/.pearrc"

What does that mean?
Note by: gronf
The instruction

"download a copy of http://pear.php.net/go-pear.phar and save it as go-pear.php"

is not working. I only get a lot of errors in function.unserialize and function.unpack.
Note by: christian@stadegaart.name
I ran into a problem when running 'pear install -o PEAR' for a shared installation via SSH.

The server's PEAR version is 1.7.1. When running 'pear install -o PEAR' dependencies are installed as well. But an issue rises when one of these dependencies require a higher PEAR version than the version your remote server is running.

In my case Console_Getopt 1.3.1 is being installed because Console_Getopt is a dependency of PEAR. But this won't work, since Console_Getopt 1.3.1 needs PEAR 1.8.0 or newer.

To make this work, first install a lower version of the dependency which supports your server's PEAR version, in my case Console_Getopt 1.2.3. The command for this is 'pear install Console_Getopt-1.2.3'. After that 'pear install -o PEAR' works fine. After the PEAR user installation, I upgraded Console_Getopt manually, because my own PEAR copy is 1.9.4 and not 1.7.1.

Also make sure you run 'pear update-channels' after you created .pearrc.
Note by: adcomitus (whatever) gmail
Hy.
I had some troubles installing 'HTML_templates_sigma' trough FTP. Here is the additional steps I had to take:

In step 5, where it states (for Unix) '$ pear config-create /home/username/pear .pearrc', I removed the '/pear'. This will create a 'pear' folder inside your '/username/pear' folder. KISS.

Add the 'php' folder in 'pear' on the remote server to the include path. Something like 'set_include_path( get_include_path() . PATH_SEPARATOR . PATH_SEPARATOR . '/(relative-path-to-your-remote-pear-folder/php');' in my script;

I could not simply use remote-install. I saw this in a German forum (luckily the code was in a box!):
'pear -c remote.conf remote-install --onlyreqdeps HTML_Template_Sigma'
I had to add pear complete path of pear and remote.conf (i.e., './remote.conf'), but I'm guessing that's just my Linux distro.

I don't really know much about this, so I don't know how much of this is really needed for everybody, and how much was only from my own specific case. But maybe it will help someone else.
Be well.

Note by: james
'go pear' is actually at http://pear.php.net/go-pear
Note by: alexandre.grivel@computershop.ch
Il faudrai corrigé ces deux lignes qui se trouve dans:

Installer une copie locale de PEAR via ftp, ftps ou sftp:

1) 3. Notez le !chemon! complet vers votre dossier utilisateur.

2) Voici les séquences !nécessiare! pour que cela fonctionne. :