Book Image

The PEAR Installer Manifesto

By : Gregory Beaver
Book Image

The PEAR Installer Manifesto

By: Gregory Beaver

Overview of this book

PEAR stands for PHP Extension and Application Repository, and its primary purpose is to support code re-use. PEAR provides both an advanced installer and a code repository at PEAR code is organized into discrete re-usable components called packages. A package consists of a group of files and a descriptor file called package.xml that contains metadata about the package's contents, such as the package version, any special dependencies, and textual information such as the package description and authors. The software that transforms a package from an inert grouping of files into a dynamic software package is called the PEAR Installer and is itself a PEAR package. In other words, the PEAR Installer can be used to upgrade itself. It truly is a very powerful application. In short, the PEAR Installer is one of the most effective tools for managing a high-quality software library, high-quality applications, or high-quality websites. This book will show you a new way of organizing your PHP development, by leveraging the full power of the PEAR Installer. In a sense, the PEAR Installer is a step above a software design pattern, a meta-development pattern that can be used to systematically organize all of your PHP development. You will learn how to organize your code into packages using the package.xml format. You will learn about the revolutionary new PEAR Channel concept, and how to safely and reliably depend on external PHP libraries from sources such as and other PEAR channels. You will learn about the PEAR_PackageFileManager package, and how to customize individual installations of your PHP code through file roles, file tasks, and post-installation scripts. In addition, you will learn how to use the power of PEAR to manage your web projects with the PEAR installer to bring the power of versioning and rollbacks to your live website. The synergy of the PEAR Installer and a revision control system like CVS or Subversion is also explored in depth. Next, you will learn how to set up your own PEAR Channel for distributing PHP applications, both open-source and proprietary closed-source PHP applications that can be secured using technology already built into the PEAR Installer. Finally, you will learn how to embed the PEAR Installer inside your own web application in order to manage plug-ins from a remote server. The book covers in detail designing a custom plug-in system for a fictitious blog application. The plug-in system is used to manage templates, and the PEAR Installer is used to manage the details of querying the remote server for templates, handling dependencies between versioning, and doing the actual installation process as well.
Table of Contents (11 chapters)
The PEAR Installer Manifesto
About the Author
About the Reviewers

Synchronizing to a Server with no Shell Access Using PEAR_RemoteInstaller

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 ( 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


Publication Limitation

Note that at the time this book was written, the latest version of PEAR_RemoteInstaller was 0.3.0, stability alpha. To install, you will need to append alpha or -0.3.0 as in:

$ 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:

echo __FILE__;

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


Once you have this information, you can begin

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

This will display something similar to:

Auto-discover new Channels auto_discover <not set>
Default Channel default_channel
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 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 (, 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

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
$ pear c pear.ini remote-install savant/Savant3

If everything works, you will see:

remote install OK:

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.


Errors about alpha/beta

If installation fails with a notice about preferred state, try appending -alpha as in:

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


This will work because it instructs the installer to temporarily ignore your preferred_state configuration variable and to instead download the latest alpha or more stable version. In other words, with a preferred_state of stable, if Savant3 version 3.2.0 stable is available, it will be installed. However, if version 3.2.1 alpha is available, a newer version, it will not be installed because its stability is too low. However, by appending -alpha, the installer is instructed to instead grab the newest version 3.2.1 and install that version.

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


The rsync Method

If you are developing a complex website for a customer who has money, it may be best to develop on an identical machine with identical software and hardware configuration. Set up the entire website locally, and synchronize it with the remote website using rsync. This still works well with using source control and a PEAR-installable package, as development should be synced with discrete package versions.