The PEAR Installer Manifesto: The PEAR Installer maintainer shows you the power of this code management and deployment system to revolutionize your PHP application development

The PEAR package repository at pear.php.net is the official PEAR channel, and is the oldest PEAR channel, predating the concept of PEAR channels by five years. Many popular packages are distributed via pear.php.net such as HTML_QuickForm, DB_DataObject, MDB2, and PhpDocumentor. Most of the time, when people refer to "PEAR" in the abstract, one of the packages distributed at pear.php.net is what they are talking about.

The package repository at pear.php.net was established in 1999 by Stig Bakken and a few others to help fill in the gaps in PHP. PEAR's first usable release coincided with approximately PHP version 4.0.6. At this time, PEAR was designed as a framework, providing several base classes and an installer to manage them. The PEAR package provided two of the base classes, PEAR and System. The PEAR class, located in file PEAR.php was designed to provide basic error handling and a few other add-ons beyond what is available in PHP's internal trigger_error() error handling.

Several basic packages were designed to handle common tasks, such as DB for database-independent code, HTML_Form for HTML Forms, Log for basic logging, and this list expanded (to make a long story short) until the present day where there are 374 packages available from pear.php.net at the time of this chapter, and more on the way via pending proposals.

PEAR has had its share of woes since its rosy beginnings. PHP has evolved, and introduced several features that supersede the functionality provided by PEAR. For instance, the Exception class introduced in PHP 5.0.0 provides similar functionality to the PEAR_Error class, the PDO extension provides similar functionality to the DB package, and so on. In addition, as PEAR has grown, some problems in its initial design as a repository have surfaced and led to both minor and major crises.

Several good things have come out of these growing pains, including the efficient PEPr proposal system for proposing new packages, and a strong push towards both stability and innovation. Much of the push towards innovation is coming from external pressure due to the advent of new ideas from projects like SolarPHP, eZ components, Phing, Propel, Agavi, and the Zend Framework. However, one of the significant forces of innovation in PEAR is the PEAR installer itself, specifically with the new features found in version 1.4.0 and newer.

One of the crucial new features in the newer versions of the PEAR installer is PEAR channels. A PEAR channel is simply a server that provides packages like pear.php.net, and also provides special web services that enable the PEAR installer to communicate with the server; channels are covered in detail in Chapter 4.

Most books that discuss PEAR spend a great deal of time on using popular packages from the PEAR repository (http://pear.php.net) such as DB (http://pear.php.net/DB) or HTML_QuickForm (http://pear.php.net/HTML_QuickForm). This book takes a different route, instead focusing exclusively on the power surrounding the installation mechanism of the PEAR installer itself. When you see a reference to PEAR in this book, you should know that it is in fact a reference to the PEAR installer (http://pear.php.net/PEAR) and not to the repository at large.

The PEAR installer consists of four abstract task-oriented sections:

Fortunately, as an end-user, you don't really need to know or care about any of these beyond the way that your application communicates with the installer and how people will actually use the installer to install your code.

First and foremost, you need to understand how PEAR actually installs its packages, as this is a little different from the old unzip-and-go philosophy. PEAR categorizes files into different types, and installs each file type differently. For instance, files of type php will be installed into a subdirectory of the user's configuration variable php_dir. So if the user has set php_dir to /usr/local/lib/php/pear, a file that is packaged in directory Foo/Bar/Test.php will be installed into /usr/local/lib/php/pear/Foo/Bar/Test.php. Files of type data will be installed into a subdirectory of the user's configuration variable data_dir, but unlike PHP files, data files are installed into their own private sub-directory based on the package name. If the user has set data_dir to be /usr/local/lib/php/data and the package is named "TestPackage", a file that is packaged in directory Foo/Bar/Test.dat will not be installed at /usr/local/lib/php/data/Foo/Bar/Test.dat, but instead be installed in /usr/local/lib/php/data/TestPackage/Foo/Bar/Test.dat! This and other details of PEAR's installation are covered in Chapter 2.

Next, you need to know a bit about how PEAR knows which files are in a package, what it needs in order to work (i.e. "This package only works in PHP 4.3.0 and newer, and needs any version of the DB_DataObject package, and only versions 1.2.3 of the Log package, recommending version 1.4.6 be installed"), or its dependencies. This information is also covered in Chapter 2, where we learn about the package.xml file format.

After reading Chapters 2 and 3, you should know enough about PEAR to manage the creation of your own packages for local installation, or to propose a new package to the official pear.php.net repository. Should you wish to distribute your packages for others to use, whether it be free, for private clients, or for sale, you will need to have an understanding of how PEAR channels work. Setting up a channel server is a relatively easy task. At the time of writing this chapter, there was one option available for setting up a channel, but several potential competing options are on the verge of completion. It's an exciting time to be involved in PHP! Setting up your own channel is covered in Chapter 5.

Of course, not everyone is distributing their code publicly. Most developers are busy designing their own websites either by themselves or in a team. The PEAR installer is a highly effective tool for managing a complete website when used in conjunction with a revision control system. Chapter 4 covers this topic in great detail.

In short, the PEAR installer is one of the most effective tools for managing a high-quality software library, high-quality application, or a high-quality website.

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:

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

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

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

include 'PEAR.php';

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.

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 http://pear.php.net/go-pear 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 http://pear.php.net/go-pear

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

$ php go-pear.php

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:password@proxy.myhost.com: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).

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

Christian Weiske over at http://www.gnope.org 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 http://pear.php.net/PEAR_Frontend_Gtk2. 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.