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

Installing the PEAR Installer

There are three methods of acquiring PEAR. The first way has been available since PHP 4.2.0, and simply involves installing PHP and either configuring --with-pear (on Unix) or running go-pear from within the PHP directory.


I'm Running Windows and my PHP doesn't have PEAR in it, Where is it?

If you are running PHP version 5.1 or older, to get a copy of PHP that bundles PEAR, you need to download the .zip file rather than the Windows installer (.msi). PHP 5.2.0 and newer has vastly improved the Windows Installer (.msi) distribution, and this is recommended to acquire PEAR. The installer (at least at this time) is not really useful at all, as it is never updated unless there is a critical error. As such, getting the truly useful elements of PHP requires using the .zip file. Never fear, PHP is pretty much an unzip-and-go language on Windows.

If I were less diplomatic, I might say something like "Don't even think about running PHP on Windows as a production server." However, I do feel it is important to say this: "In my opinion, running PHP on Windows as a production server is not worth the effort and expense." Although it can be done, the only reason it should ever be considered is if your boss will fire you on installing Unix. Or you work for a company that maintains the Windows operating system. In that case, you will be forgiven.

The second involves grabbing the go-pear script from, and saving it as go-pear.php, then running this file. Last, there are a few unofficial sources for acquiring PEAR, the most notable being the Gnope installer that sets up PHP 5.1, PEAR, and PHP-GTK2 in one step.

PEAR Bundled with PHP

As mentioned above, if you are running Windows, installing PEAR is relatively simple. Running the go-pear command will run the installation script. In addition, as of PHP version 5.2.0, there is an excellent Windows Installer-based (.msi file extension) installation mechanism that bundles PEAR in its distribution, and is

recommended. For earlier PHP versions, in order to obtain a bundled PEAR, you must download the .zip file distribution instead of the .msi Windows Installer-based installation mechanism.

If you are running Unix, you need to use at least this minimal configure line to set up PEAR:

$ ./configure --enable-cli --enable-tokenizer --with-pcre-regex -- enable-xml

To take full advantage of PEAR, it is a good idea to enable the zlib extension for accessing compressed PEAR packages as well:

$ ./configure --enable-cli --enable-tokenizer --with-pcre-regex -- enable-xml --with-zlib

When you install, be sure that you have full write access to the directory that PEAR will be installed in (usually /usr/local/lib, but configurable with the --prefix option; /lib is appended to the prefix). When you install PEAR, it will also install the needed packages Console_Getopt and Archive_Tar.

$ make install-pear
Installing PEAR Environment: /usr/local/lib/php/
[PEAR] Archive_Tar - installed : 1.3.1
[PEAR] Console_Getopt installed : 1.2
pear/PEAR can optionally use package "pear/XML_RPC" (version >= 1.4.0)
[PEAR] PEAR - installed : 1.4.9
Wrote PEAR system config file at: /usr/local/etc/pear.conf
You may want to add: /usr/local/lib/php to your php.ini include_path

After completing PEAR installation, as the last line of installation suggests, you will want to ensure that PEAR is in php.ini's include_path setting. The easiest way to determine this is to first find php.ini:

$ php i |grep php[.]ini
Configuration File (php.ini) Path => /usr/local/lib

This example shows that php.ini is located at /usr/local/lib/php.ini. Open this file with your favorite editor, and either find the line that says "include_path=" or add a new one that is something like this:


Of course, substitute the suggested path from your specific installation (the last line of output) for /usr/local/lib/php.


What is this so-called "include_path"?

Oh dear—time to pull out the PHP manual again, to be specific, To summarize, the include statement and its cousins include_once, require and require_once all serve to dynamically include external PHP code. If you pass a full path like /path/to/my.php:

include '/path/to/PEAR.php';


then naturally /path/to/my.php will replace the include statement and be executed. If, however, you pass in a relative path like:

include 'PEAR.php';

This will instead search through the include_path and try to find a PEAR.php file. If the include_path is .:/usr/local/lib/php, then PHP will first try to find PEAR.php in the current directory (.), and if it is not found, then it will search for PEAR.php in /usr/local/lib/php/PEAR.php. This allows customization of library locations on the disk, which is precisely what PEAR attempts to accomplish.

If you are running Windows, the go-pear batch file will prompt you to choose a location to install PEAR, defaulting to either C:\php4 for version 4, C:\php5 for version 5.0, or the current directory for version 5.1 or newer. Unless you have a compelling reason to install PEAR elsewhere, it is a good idea to accept the default locations, as it will save some potential trouble later on. If you are installing PEAR from version 5.1.0 or newer, the installer will ask you if you are installing a local or a system installation.

Are you installing a system-wide PEAR or a local copy?
(system|local) [system] :

Simply hit Return to install a system-wide PEAR (in general, with installation of PEAR, if you don't know what it is asking you, always choose the default value). Next, it will ask you for a location to install your copy of PEAR:

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) : C:\php51
2. Binaries directory : C:\php51
3. PHP code directory ($php_dir) : C:\php51\pear
4. Documentation directory : C:\php51\pear\docs
5. Data directory : C:\php51\pear\data
6. Tests directory : C:\php51\pear\tests
7. Name of configuration file : C:\php5\pear.ini
8. Path to CLI php.exe : C:\php51\.
1-8, 'all' or Enter to continue:

Change any values you wish to change by typing the number in front of the item and hit Enter. If you wish to change the installation base directory, type 1 and hit Enter. If you want to modify all of the values, type all and hit Enter. Once you are satisfied, hit Enter without typing anything to continue. At this point, it will install packages (which should look similar to what is displayed in Unix installation of PEAR) and finally ask if you would like to modify php.ini. If you choose to do this, it will automatically update the include_path setting in php.ini, and you will be good to go.

Installation for PHP Versions Older than 5.1.0

If you have a version of PHP older than 5.1.0 and wish to install PEAR, you should not use the bundled version of PEAR, but instead install PEAR via the go-pear script. To retrieve this script, browse to in any web browser and save it to disk as go-pear.php, or if on Unix, then you have the wget command:

$ wget O go-pear.php

Once you have go-pear.php accessible, simply run it:

$ php go-pear.php


Why Just for PHP 5.1.0 and Older?

As I was asked once, "Why is it important to only use the go-pear script for PHP versions older than 5.1.0? Will this not also change over time when there is a new PEAR installer released with PHP 6.0.0?"

The reason for this has to do with how go-pear works. The go-pear script is a brilliant design that extracts key files directly from CVS based on their release tags and then downloads packages and installs them based on their latest stable version. Although brilliant, this is a dangerous approach that guarantees your installation will break if there is a problem in CVS.

The PEAR installer bundled with PHP version 5.1.0 and newer is in fact self-contained, does not contact the Internet at all, and is tested and guaranteed to work with that version of PHP. Once PEAR is installed, grabbing the latest version is both easy and safer than using go-pear:

pear upgrade PEAR

Output will be very similar to go-pear from bundled PHP, but will instead begin with:

$ php go-pear.php
Welcome to go-pear!
Go-pear will install the 'pear' command and all the files needed by
it. This command is your tool for PEAR installation and maintenance.
Use 'php go-pear.php local' to install a local copy of PEAR.
Go-pear also lets you download and install the PEAR packages bundled
with PHP: DB, Net_Socket, Net_SMTP, Mail, XML_Parser, PHPUnit.
If you wish to abort, press Control-C now, or press Enter to continue:

Because go-pear requires internet access, the next question will be for a proxy. Be sure that if you are behind a firewall, you know whether you need to use a proxy:

HTTP proxy (http://user:[email protected]:port), or Enter for none::

The next step of the installation process should look pretty familiar:

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 prefix : C:\php51
2. Binaries directory : $prefix
3. PHP code directory ($php_dir) : $prefix\pear
4. Documentation base directory : $php_dir\docs
5. Data base directory : $php_dir\data
6. Tests base directory : $php_dir\tests
7. Temporary files directory :
8. php.exe path : C:\php51\php.exe
1-8, 'all' or Enter to continue:

After choosing location, go-pear will download the needed code, and install PEAR packages. It will also ask whether to install a few more packages, and at the end whether to modify php.ini.

If you are feeling adventurous, you might also simply try opening go-pear.php inside a web browser. This will install the web front end to PEAR, which is very nice but not as actively maintained as the Command-Line Installer (CLI).

Other Unofficial Sources

Before we continue, it is important to note that everything in this section is unofficial and therefore not supported by the folks over at Any problems you encounter are the domain of the site from which you downloaded it! Ok, enough preambles.

Christian Weiske over at has been working hard at both making PHP-GTK2 work in PHP 5.1 and making it easy to install PHP-GTK2 applications using PEAR. As such, he worked very closely with me to create a GTK2 front end to the PEAR installer, which is now available through PEAR at This is the official PHP-GTK2 front end for PEAR. The front end requires that PEAR already be installed in order to use it.

However, Christian has taken it up a notch, and has written a Windows installer that provides the latest stable PHP 5.1, PEAR, and PHP-GTK2 that sets up everything for you. This is a great way to get started with PEAR, if you are new to the whole process. The current release is version 1.0, but this is an alpha release, so things may not work properly.

The first thing you should note is that if you have already set up PHP, the PATH environment variable in Windows may cause some conflicts with the existing PHP installation. In short, don't try to install both a regular copy of PHP and the gnope PHP unless you know what you are doing.

Installing gnope is really easy, just download the installer and run it. The prompts are just like any other Windows installation.