Once you have successfully installed PEAR on a development machine, how do you properly install PEAR on the live server? For many developers, this is simply a matter of repeating the same steps on the live server that are performed on the development server. However, many developers out there have the misfortune of using a shared hosting provider who does not provide a shell, but does provide PHP. In the past, this essentially eliminated any possibility of successfully installing PEAR packages.

As of PEAR 1.4.0, this is no longer an issue, thanks to the PEAR_RemoteInstaller package (http://pear.php.net/PEAR_RemoteInstaller). This package provides special commands for synchronizing a customized PEAR server and the remote server. Unlike other solutions, the only tools required to implement this are PHP 5 on your development machine, and access to an FTP server.

To get started, install PEAR_RemoteInstaller onto your development machine:

$ pear install PEAR_RemoteInstaller

$ pear install PEAR_RemoteInstaller-alpha

$ pear install PEAR_RemoteInstaller-0.3.0

Next, you need to create a configuration file for the remote machine using the config-create command. However, before this is possible, it is important to know the full path to your host. The easiest system to determine this is to run this simple script on your web host:

<?php
echo __FILE__;
?>

Save this as me.php, and upload it to your web host. When run, this will output something similar to:

/home/myuser/htdocs/me.php

Once you have this information, you can begin

$ pear config-create /home/myuser pear.ini

This will display something similar to:

CONFIGURATION (CHANNEL PEAR.PHP.NET):
=====================================
Auto-discover new Channels auto_discover <not set>
Default Channel default_channel pear.php.net
HTTP Proxy Server Address http_proxy <not set>
PEAR server [DEPRECATED] master_server <not set>
Default Channel Mirror preferred_mirror <not set>
Remote Configuration File remote_config <not set>
PEAR executables directory bin_dir /home/myuser/pear
PEAR documentation directory doc_dir /home/myuser/pear/docs
PHP extension directory ext_dir /home/myuser/pear/ext
PEAR directory php_dir /home/myuser/pear/php
PEAR Installer cache directory cache_dir /home/myuser/pear/cache
PEAR data directory data_dir /home/myuser/pear/data
PHP CLI/CGI binary php_bin C:\php5\php.exe
PEAR test directory test_dir /home/myuser/pear/tests
Cache TimeToLive cache_ttl <not set>
Preferred Package State preferred_state <not set>
Unix file mask umask <not set>
Debug Log Level verbose <not set>
PEAR password (for password <not set> maintainers)
Signature Handling Program sig_bin <not set>
Signature Key Directory sig_keydir <not set>
Signature Key Id sig_keyid <not set>
Package Signature Type sig_type <not set>
PEAR username (for username <not set> maintainers)
User Configuration File Filename C:\test\pear.ini
System Configuration File Filename #no#system#config#
Successfully created default configuration file "C:\test\pear.ini"

Once you have the pear.ini file, upload it to your remote web host and save it in the /home/myuser directory (the default directory of your FTP login). Next, we need to create our local working copy of PEAR:

$ mkdir remote
$ cd remote

If you are running Windows:

$ pear config-create w C:\remote\ pear.ini

Otherwise (assuming you are running as user foo on your development machine):

$ pear config-create /home/foo pear.ini

Next, determine the kind of FTP connection you use. You'll need to know your username and password for accessing FTP, and the host name. For our example, we will use myuser and password as the user/password combination, and yourwebsite.example.com as the host.

If you use regular FTP, you will want to do:

$ pear c pear.ini config-set remote_config ftp://myuser:[email protected]/

If you use FTPS, you will want to do:

$ pear c pear.ini config-set remote_config ftps://myuser:[email protected]/

If you use SFTP, you will want to do:

$ pear c pear.ini config-set remote_config ssh2.sftp://myuser:[email protected]/

In order to use SFTP, you need to install the SSH2 extension from pecl.php.net (http://pecl.php.net/ssh2), an excellent extension written by Sara Golemon. On Unix, this is simple; SSH2 can be installed via:

$ pecl install ssh2

On Windows, php_ssh2.dll should be distributed with your distribution of PHP 5. If not, you can grab a copy from http://pecl4win.php.net.

Once we reach this stage, the next step is to try installing a package. Let's install Savant3, an excellent template engine for PHP 5+ that utilizes the elegance of PHP itself as a templating language.

$ pear c pear.ini channel-discover savant.pearified.com
$ pear c pear.ini remote-install savant/Savant3

If everything works, you will see:

remote install OK: savant.pearified.com/Savant3-3.0.0

At this point, fire up your FTP browser and you'll see that the files were uploaded to /home/myuser/pear/php/Savant3.php and to the /home/myuser/pear/php/Savant3 directory.

$ pear -c pear.ini remote-install savant/Savant3-alpha

You may be thinking, how does this differ from just extracting the files and uploading them manually? The answer becomes apparent when managing more complex packages like DB_DataObject or LiveUser. Both of these packages have dependencies that must be installed in order to work. Although it is possible to manually install them and upload, it is very easy to forget a dependency. Worse, the entire process has to be repeated upon upgrade.

Installing DB_DataObject with its dependency on PEAR, Validate, and DB is as simple as:

$ pear c pear.ini remote-install o DB_DataObject

The same is true of upgrading:

$ pear c pear.ini remote-upgrade o DB_DataObject

Uninstalling is also simple, and responds to the full strength of the PEAR installer's dependency validation:

$ pear c pear.ini remote-uninstall DB_DataObject